[phobos] Phobos Style Guide: Commenting out code

[Jonathan M Davis]

On Monday, July 02, 2012 12:56:29 Jacob Carlborg wrote:
> * Mentioning of how abbreviations are written with regards to upper and
> lower case, i.e.
> 
> httpFoo
> HTTPFoo
>
> This has been asked about in the newsgroups several times.

I intend to add that. I was just looking to address the comments issue before 
making any more updates, because it was one of the few issues where there was 
disagreement and needs to be resolved.
 
> * How should the licensee information look like
> 
> For example, I think it's unnecessary to repeat the license information
> twice. First once, using D-style, with copyright, license and author
> information in separate Ddco sections:
> 
> https://github.com/D-Programming-Language/phobos/blob/master/std/getopt.d#L1
> 7
> 
> Then second, using the Boost-style with the copyright, license and author
> information combined:
> 
> https://github.com/D-Programming-Language/phobos/blob/master/std/getopt.d#L2
> 7
> 
> Currently it seems to be a mix of these style in Phobos but I prefer to only
> use the Ddoc sections, like this:
> 
> https://github.com/D-Programming-Language/phobos/blob/master/std/net/isemail
> .d

They should only list them once, but I'm not sure that that's something that 
actually needs to be mentioned in the style guide. I believe that it's only 
older stuff which has it twice.

> * How should doc comments look like

What are you looking for here? The comment markers must be /++ +/, /** */, or 
/// per the language, so the only reason to mention that is if we required a 
specific one of them to be used, and we're not in agreement on which style to 
use, but since it doesn't affect the docs themselves, I don't see any reason to 
specify which to use. And if you're talking about what should go in the 
comments, what would we need to say beyond that it should say what the 
function does? That it needs to have examples (preferrably compilable 
examples)? I'm not quite sure what we'd really need to say about ddoc 
comments. Overall, it seems fairly obvious to me what should go in a ddoc 
comment - pretty much the same thing which should go in any function comment. 
What do you think needs further explanation or requirements?

- Jonathan M Davis