Embedded Documentation Suggestion - Inline param comments

[Robby]

Johan Granberg wrote:
> 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++
+1