>________________________________
>From: Andrei Alexandrescu <andrei at erdani.com>
>
>On 03/31/2011 08:29 AM, Steve Schveighoffer wrote:
>> One thing I've noticed about std.container, and it makes it very hard for me to read: Putting all ddoc comments with no indentation. In particular, I have a very hard time seeing where a class or struct ends. Andrei, there must be a good reason for you to do this, can you explain that? I'd really prefer that the comments are put at the same indentation as the code being commented.
>
>Documentation comments are meant to be multiline and treated as regular text. As such, I thought it's natural that they extend from the left edge as a deeply indented comment would be difficult to read (and write for some).

It isn't often that ddoc comments are deeply indented.? I'd say at most 2 levels, which gives you 8 less characters out of an 80-character line.? In addition, the line breaks in the file do not dictate line breaks in the generated docs, so this is really a non-issue, the ddoc generator will reformat as necessary.


But in any case, the issue is that it messes up the indentation of the class/struct being commented.? I can't easily see where a struct begins or ends, because the text is always bringing me back to the left edge.


To me it looks as bad as this:

class A
{
void foo();
void bar();
struct Range
{
@property bool empty() const;
...
}
}

Especially if syntax highlighting isn't used (which doesn't seem to be the case for github on std.container, see https://github.com/D-Programming-Language/phobos/blob/master/std/container.d )

>
>> Also, can we standardize the comment style, at least for ddoc comments? I've seen a few different styles in phobos. My favorite is:
>>
>> /**
>> * comment
>> */
>>
>> or
>>
>> /++
>> + comment
>> +/
>>
>> I do not like this:
>>
>> /**
>> comment
>> */
>>
>> because it's more difficult to distinguish commented lines from normal lines.
>
>Indeed your favorite style is more difficult to maintain. Also, if a parenthesized construct crosses a line, ddoc gets confused.

Another option is to have a more distinct header/footer for the comment, i.e.:

/**********************
comment
***********************/

What I find wrong with the style I disliked is that the opening/closing comment tags get lost in the noise with my visual scanning, whereas if they all line up with a common line prefix, then I can see the comment as a whole much easier.

BTW, my preferred style is really easy for me to maintain, but it's specific to my editor and key shortcuts (vim automatically adds the * prefix, and with one keystroke, I can insert needed line breaks at 80 chars along with the * prefix), so I suppose it's a valid point that maintenance can be an issue for some who don't have an editor that performs those tasks easily.

-Steve

On 03/31/2011 09:53 AM, Steve Schveighoffer wrote:
[snip]

All fine by me.

Andrei