Embedded Documentation Suggestion - Inline param comments

[T.J. Crowder]

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