
<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On 2 jul 2012, at 19:27, Jonathan M Davis wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div>On Monday, July 02, 2012 12:56:29 Jacob Carlborg wrote:<br><font class="Apple-style-span" color="#007225"><br></font>I intend to add that. I was just looking to address the comments issue before <br>making any more updates, because it was one of the few issues where there was <br>disagreement and needs to be resolved.<br></div></blockquote><div><br></div><div>I see, good.</div><div><br></div><blockquote type="cite"><div>What are you looking for here? The comment markers must be /++ +/, /** */, or <br>/// per the language, so the only reason to mention that is if we required a <br>specific one of them to be used, and we're not in agreement on which style to <br>use, but since it doesn't affect the docs themselves, I don't see any reason to <br>specify which to use. And if you're talking about what should go in the <br>comments, what would we need to say beyond that it should say what the <br>function does? That it needs to have examples (preferrably compilable <br>examples)? I'm not quite sure what we'd really need to say about ddoc <br>comments. Overall, it seems fairly obvious to me what should go in a ddoc <br>comment - pretty much the same thing which should go in any function comment. <br>What do you think needs further explanation or requirements?<br></div></blockquote></div><div><br></div><div>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:</div><div><br></div><div>* Using single line comments as multiline comments:</div><div><br></div><div>/// Multiline </div><div>/// comment</div><div><br></div><div>* Using multiline comments:</div><div><br></div><div>/**</div><div>Multiline</div><div>comment</div><div>*/</div><div><br></div><div>* Using multiline comments in Java style:</div><div><br></div><div>/**</div><div> * Multiline</div><div> * comment</div><div> */</div><div><br></div><div>* Using multiline comment for single line comment</div><div><br></div><div>/** Single line comment */</div><div><br></div><div>/++</div><div>Nested comment style</div><div>+/</div><div><br></div><div>* Putting single line comments before or after the symbol</div><div><br></div><div>Then when various sections that is not consistently used, like:</div><div><br></div><div>* Return</div><div>* Params</div><div>* Examples</div><div>* See_Also</div><div>* Standards</div><div>* Throws</div><div><br></div><div>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. </div><br><div>

<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; ">-- <br>/Jacob Carlborg</span>

</div>

<br></body></html>