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

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++

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

Speaking about documenting code, it would be great to have restructuredtext markup support.

-- 
serg.