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