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