• T.J. Crowder (64/64) Feb 06 2007 Hi,
• Johan Granberg (3/82) Feb 06 2007 I like this suggestion.
• Robby (2/87) Feb 06 2007 +1
• Serg Kovrov (4/4) Feb 18 2007 Speaking about documenting code, it would be great to have

"T.J. Crowder" <tj crowdersoftware.com> writes:

Hi,

Just heard about D and have been reading up.  Wow.  I'm coming from a C, 


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 

Johan Granberg <lijat.meREM OVE.gmail.com> writes:

T.J. Crowder wrote:

 Hi,
 
 Just heard about D and have been reading up.  Wow.  I'm coming from a C,

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

Robby <robby.lansaw gmail.com> writes:

Johan Granberg wrote:
 T.J. Crowder wrote:
 
 Hi,

 Just heard about D and have been reading up.  Wow.  I'm coming from a C,

 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

Serg Kovrov <kovrov no.spam> writes:

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

-- 
serg.