[Issue 13270] New: ddoc can't find parameters of ditto'd function overloads

Fri Aug 8 15:27:18 PDT 2014

https://issues.dlang.org/show_bug.cgi?id=13270

          Issue ID: 13270
           Summary: ddoc can't find parameters of ditto'd function
                    overloads
           Product: D
           Version: D2
          Hardware: x86
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: DMD
          Assignee: nobody at puremagic.com
          Reporter: hsteoh at quickfur.ath.cx

Ddoc params documentation doesn't work well with ditto'd overloads.
------
/**
 * My overloaded function.
 *
 * Params:
 *      task = String description of stuff to do.
 *      tasks = Array of descriptions of stuff to do.
 *      maxJobs = Max parallel jobs to run while doing stuff.
 */
void doStuff(string task) {}

/// ditto
void doStuff(string[] tasks, int maxJobs) {}
------

Ddoc output:
------
<html><head>
        <META http-equiv="content-type" content="text/html; charset=utf-8">
        <title>test</title>
        </head><body>
        <h1>test</h1>
        <!-- Generated by Ddoc from test.d -->
<br><br>
<dl><dt><big><a name="doStuff"></a>void <u>doStuff</u>(string <i>task</i>);
<br><a name="doStuff"></a>void <u>doStuff</u>(string[] <i>tasks</i>, int
<i>maxJobs</i>);
</big></dt>
<dd>My overloaded function.
<br><br>
<b>Params:</b><br>
<table><tr><td>string <i>task</i></td>
<td>String description of stuff to do.</td></tr>
<tr><td>tasks</td>
<td>Array of descriptions of stuff to do.</td></tr>
<tr><td>maxJobs</td>
<td>Max parallel jobs to run while doing stuff.</td></tr>
</table><br>

</dd>
</dl>

        <hr><small>Page generated by <a
href="http://dlang.org/ddoc.html">Ddoc</a>. </small>
        </body></html>
------

A few points of note:
1) ddoc is unable to find the correct type of 'tasks' and 'maxJobs'. Seems that
it doesn't know to look at subsequent ditto'd functions to determine parameter
types.

2) compiling with -w produces this message, which reinforces the observations
made in (1):
------
test.d(9): Warning: Ddoc: function declaration has no parameter 'tasks'
test.d(9): Warning: Ddoc: function declaration has no parameter 'maxJobs'
test.d(9): Warning: Ddoc: parameter count mismatch
------

One may argue that these functions really should have separate ddoc comments,
but the problem is, this kind of unified documentation for overloads is quite
common in Phobos, for example, std.process.pipeProcess, where it makes more
sense to document them all together.

In short, ddoc should check all ditto'd overloads of a function in order to
ascertain parameter types, and when checking the validity of the Params:
section.

--