digitalmars.D.bugs - [Issue 13270] New: ddoc can't find parameters of ditto'd function
- via Digitalmars-d-bugs (76/76) Aug 08 2014 https://issues.dlang.org/show_bug.cgi?id=13270
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 puremagic.com Reporter: hsteoh 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. --
Aug 08 2014