[phobos] Phobos Style Guide: Commenting out code

[Jacob Carlborg]

On 2 jul 2012, at 19:27, Jonathan M Davis wrote:

> On Monday, July 02, 2012 12:56:29 Jacob Carlborg wrote:
> 
> 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.

I see, good.

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


It's fairly obvious that it needs to be ddoc comments, otherwise it won't work. But there are various styles that can be used:

* Using single line comments as multiline comments:

/// Multiline 
/// comment

* Using multiline comments:

/**
Multiline
comment
*/

* Using multiline comments in Java style:

/**
 * Multiline
 * comment
 */

* Using multiline comment for single line comment

/** Single line comment */

/++
Nested comment style
+/

* Putting single line comments before or after the symbol

Then when various sections that is not consistently used, like:

* Return
* Params
* Examples
* See_Also
* Standards
* Throws

We could have guidelines saying when these sections should and shouldn't be used. I don't know how to picky we want to be with the documentation but these were the things I had in mind. 

-- 
/Jacob Carlborg

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/phobos/attachments/20120702/f6c9f744/attachment.html>