Documenting parameters [was: Re: Worst Phobos documentation evar!]
Joseph Rushton Wakeling via Digitalmars-d
digitalmars-d at puremagic.com
Sun Dec 28 06:49:29 PST 2014
On 28/12/14 02:00, Walter Bright via Digitalmars-d wrote:
> Let me enumerate the awesomeness of its awfulness:
>
> 1. No 'Return:' block, though it obviously returns a value.
> 2. No 'Params:' block, though it obviously has parameters.
> 3. No 'Example:' block
> 4. No comparison with other 'encode' functions in the same module.
> 5. No description of what 'Tgt' is.
> 6. No description of what 'Src' is.
'Params:' provides a special case for documenting input parameters, so you can
write something like,
/**
* Params:
* n = some description
*/
void foo(int n)
{
...
}
and ddoc will generate a nice descriptive:
<b>Params:</b><br>
<table><tr><td>int <i>n</i></td>
<td>some description</td></tr>
</table>
Is there an existing equivalent that can be used for template parameters?
"Template Params:" or "TemplateParams:", for example, don't work.
BTW it would be nice if, instead of generating "hardcoded" stylistic information
like <b></b>, <i></i> and the use of <table>, the output could be more generic
and semantically marked up for use with CSS. This is something that could
contribute a lot towards making better-presented documentation.
More information about the Digitalmars-d
mailing list