Ok, some comments on this:<div><br></div><div>For each of these, please add examples, both good and bad.<br><div><br></div><div><div>+Doxygen Use in Documentation Comments</div><div>+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</div>
<div>+</div><div>+Don't duplicate the documentation comment in header file and in implementation</div><div>+file.  If the API being documented is not module-private, documentation should</div><div>+go to the header file.</div>
<div><br></div><div>Can you provide your updated wording on this? Specifically to reflect the fact that the interface specification in doxygen form should be in only one place, and for non-private interfaces they should be in the header file, but that there may even then be implementation comments (not necessarily in doxygen form) attached to an implementation in the source file.</div>
<div><br></div><div>+</div><div>+Don't duplicate function or class name at the beginning of the comment.</div><div>+For humans it is obvious which function or class is being documented and</div><div>+automatic documentation processing tools are smart enough to bind the comment</div>
<div>+to the correct declaration.</div><div><br></div><div>I would add the requirement of '\brief' headers (and how to write them) for public interfaces, and leave them optional for private interfaces.</div><div><br>
</div><div>+</div><div>+To refer to parameter names inside a paragraph use the ``\p name`` command.</div><div>+Don't use the ``\arg name`` command since it starts a new paragraph that</div><div>+contains documentation for the parameter.</div>
<div><br></div><div>What about referring to other classes? other members? global variables? Essentially, I would turn this into a cross-referencing how-to. I've observed that essentially no one does this correctly.</div>
<div><br></div><div>+</div><div>+Wrap code examples in ``\code ... \endcode``.</div><div><br></div><div>This probably needs some explanation. Specifically, it would be good to differentiate between inline code snippets and a block-level code snippets and give some examples.</div>
<div><br></div><div>+</div><div>+To document a function parameter start a new paragraph with the ``\param name``</div><div>+command.  If the parameter is used as an out parameter, use the</div><div>+``\param [out] name`` command.</div>
<div><br></div><div>You don't mention the ability to document something as in/out... Thoughts on that?</div><div><br></div><div>+</div><div>+To describe function return value use the ``\returns`` command.</div></div><div>
<br></div><div>This should probably suggest starting o new paragraph with \returns much the same as \param does.</div><div><br></div><div><br></div><div>Your document doesn't assign a fixed color to any of the doxygen bikesheds. I think it would be useful to go through those parts of doxygen and explicitly call out what form things should or shouldn't take. As a strawman proposal:</div>
<div>- Always use '\foo' commands. Never '@foo' or other forms.</div><div>- Never use trailing comments to document entities.</div><div>- Never use same-line comments (with the "//< ..." format or whatever) to document function parameters or declared variables.</div>
<div>I'm not claiming this is the perfect way to settle these bikesheds, I just think it's important to pick one way to do things, and be consistent. These are things I've seen cause inconsistency in the past.</div>
<div><br></div><div><br></div><div>I also feel this doesn't really cover some important considerations:</div><div><br></div><div>- Require that all public classes have a class-level doxygen comment.</div><div>- Require that all public free functions have a doxygen comment.</div>
<div>- Suggest that all public members of a public class have member comments.</div><div>- Suggest that any declared entity whose name does not make its use and functioning patently obvious have at least a brief doxygen comment explaining its use and purpose.</div>
<div>- Suggest adding comments to any narrow namespace containing a collection of related functions or types.<br></div><div><div>- Suggest using top-level groups to organize a collection of related functions at namespace scope where the grouping is smaller than the namespace.</div>
</div></div><div><div>- Suggest using member groups and additional comments attached to member groups to organize within a class.</div></div><div>- Suggest using '\file' markers to add the file-level comments to doxygen.</div>
<div><br></div><div>I'm not claiming we *definitely* want all of these, but we definitely want the first three, we probably want the first five, and we may want all of them. Certainly I have seen all of these in use in one place or another within the codebase, and they have made the documentation for those parts of the codebase significantly better.</div>
<div><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Sep 14, 2012 at 8:27 AM, Dmitri Gribenko <span dir="ltr"><<a href="mailto:gribozavr@gmail.com" target="_blank">gribozavr@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hello,<br>
<br>
@Chris, Chandler: CC'ing you since this an addition to the policies<br>
and I feel like I need your review.<br>
<br>
The attached patch documents current Doxygen use practices in Coding<br>
Standards.  Mostly it is obvious stuff and most new code being<br>
committed conforms to that.  Some old code does not; this might cause<br>
confusion and this is the motivation to document the correct<br>
guidelines.<br>
<br>
Please review.<br>
<span class="HOEnZb"><font color="#888888"><br>
Dmitri<br>
<br>
--<br>
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if<br>
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com">gribozavr@gmail.com</a>>*/<br>
</font></span></blockquote></div><br></div>