View mode: basic / threaded / horizontal-split · Log in · Help
February 06, 2007
Embedded Documentation Suggestion - Inline param comments
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
February 06, 2007
Re: Embedded Documentation Suggestion - Inline param comments
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++
February 06, 2007
Re: Embedded Documentation Suggestion - Inline param comments
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
February 18, 2007
Re: Embedded Documentation Suggestion - Inline param comments
Speaking about documenting code, it would be great to have 
restructuredtext markup support.

-- 
serg.
Top | Discussion index | About this forum | D home