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