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: nob...@puremagic.com Reporter: hst...@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. --