Bug 13270 – ddoc can't find parameters of ditto'd function overloads
Status
RESOLVED
Resolution
FIXED
Severity
normal
Priority
P1
Component
dmd
Product
D
Version
D2
Platform
All
OS
All
Creation time
2014-08-08T22:27:00Z
Last change time
2015-06-17T21:05:10Z
Keywords
ddoc, preapproved, pull
Assigned to
k.hara.pg
Creator
hsteoh
Comments
Comment #0 by hsteoh — 2014-08-08T22:27:18Z
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.
Comment #1 by hsteoh — 2014-08-15T01:30:59Z
*** Issue 11833 has been marked as a duplicate of this issue. ***
Comment #2 by dlang-bugzilla — 2014-08-15T10:48:49Z
Why mark the older issue as a duplicate of the newer? I think we only did that if the newer issue has valuable discussion or a pull request.
Comment #3 by hsteoh — 2014-08-15T14:58:35Z
I did that based on your comment on 11833 that it should be marked as duplicate of whatever bug that addresses the compiler deficiency, rather than just the symptom of ddoc warnings showing up for std/process.d.
But if you think it should have been done the other way round, please go ahead and update the bugs.
Comment #4 by dlang-bugzilla — 2014-08-15T15:39:01Z
Right, thanks. At the time of writing I thought this compiler bug had been filed already.
Comment #5 by timokhin.iv — 2015-05-06T21:05:03Z
*** Issue 14550 has been marked as a duplicate of this issue. ***
Comment #6 by andrei — 2015-05-06T22:29:09Z
Well looks like this is a popular duplicate :o). I preapproved it. Who wanna try at it?