Embedded Documentation Suggestion - Inline param comments

[Johan Granberg]

T.J. Crowder wrote:

> Hi,
> 
> Just heard about D and have been reading up.  Wow.  I'm coming from a C,
> Java, and C# background and D looks extremely well thought-out in many
> ways.
> 
> A suggestion on the embedded documentation front:  In addition to the
> current way of documenting params (in a Params section in the block
> comment
> above the method), allow them to be documented inline.  That way, we don't
> have to repeat the param name, which is in keeping with the guideline of
> not telling the compiler things it already knows and D's excellent
> emphasis on helping people avoid doing stupid things (like changing the
> param name and forgetting to update the documentation block's copy).
> 
> E.g., the following:
> 
> /**
>  * Counts the occurrences of a character in a string.
>  * Params:
>  *      str = The string
>  *      c   = The character
>  * Returns:
>  *      The number of times the character appears in the string
>  */
> int countOccurrences(char[] str, char c)
> {
>     ...
> }
> 
> could also be written:
> 
> /**
>  * Counts the occurrences of a character in a string.
>  * Returns: The number of times the character appears in the string.
>  */
> int
> countOccurrences(
>     char[] str,     /// The string to search.
>     char c,         /// The character to count.
>     )
> {
>     ...
> }
> 
> This is consistent with documenting other declarations.  I like to put the
> params on their own line anyway, and it would conserve a lot of vertical
> space for people like me (for those who normally put all the params on one
> line, there's no significant delta) while reducing duplication.
> 
> Just for the sake of completeness:  I don't have a good suggestion for
> doing
> something similar with the return value.  The logical extension would be
> allowing the return comment inline between the return type declaration and
> the method name:
> 
> /**
>  * Counts the occurrences of a character in a string.
>  */
> int                 /// The number of times the character appears in the
> string.
> countOccurrences(
>     char[] str,     /// The string to search.
>     char c,         /// The character to count.
>     )
> {
>     ...
> }
> 
> ...but unlike the param names there's not really a strong reason for doing
> so.
> 
> Apologies if this has been suggested before; searching for "param
> documentation" and the like didn't turn it up in the first few pages...
> 
> FWIW,
> --
> T.J. Crowder
> tj at crowdersoftware.com

I like this suggestion.

votes++