[phobos] Initial Phobos style guide proposal

[Andrei Alexandrescu]

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).

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


Andrei