[llvm-commits] [PATCH] Coding Standards: Doxygen guidelines

[Chandler Carruth]

Ok, some comments on this:

For each of these, please add examples, both good and bad.

+Doxygen Use in Documentation Comments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Don't duplicate the documentation comment in header file and in
implementation
+file.  If the API being documented is not module-private, documentation
should
+go to the header file.

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.

+
+Don't duplicate function or class name at the beginning of the comment.
+For humans it is obvious which function or class is being documented and
+automatic documentation processing tools are smart enough to bind the
comment
+to the correct declaration.

I would add the requirement of '\brief' headers (and how to write them) for
public interfaces, and leave them optional for private interfaces.

+
+To refer to parameter names inside a paragraph use the ``\p name`` command.
+Don't use the ``\arg name`` command since it starts a new paragraph that
+contains documentation for the parameter.

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.

+
+Wrap code examples in ``\code ... \endcode``.

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.

+
+To document a function parameter start a new paragraph with the ``\param
name``
+command.  If the parameter is used as an out parameter, use the
+``\param [out] name`` command.

You don't mention the ability to document something as in/out... Thoughts
on that?

+
+To describe function return value use the ``\returns`` command.

This should probably suggest starting o new paragraph with \returns much
the same as \param does.


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:
- Always use '\foo' commands. Never '@foo' or other forms.
- Never use trailing comments to document entities.
- Never use same-line comments (with the "//< ..." format or whatever) to
document function parameters or declared variables.
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.


I also feel this doesn't really cover some important considerations:

- Require that all public classes have a class-level doxygen comment.
- Require that all public free functions have a doxygen comment.
- Suggest that all public members of a public class have member comments.
- 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.
- Suggest adding comments to any narrow namespace containing a collection
of related functions or types.
- Suggest using top-level groups to organize a collection of related
functions at namespace scope where the grouping is smaller than the
namespace.
- Suggest using member groups and additional comments attached to member
groups to organize within a class.
- Suggest using '\file' markers to add the file-level comments to doxygen.

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.



On Fri, Sep 14, 2012 at 8:27 AM, Dmitri Gribenko <gribozavr at gmail.com>wrote:

> Hello,
>
> @Chris, Chandler: CC'ing you since this an addition to the policies
> and I feel like I need your review.
>
> The attached patch documents current Doxygen use practices in Coding
> Standards.  Mostly it is obvious stuff and most new code being
> committed conforms to that.  Some old code does not; this might cause
> confusion and this is the motivation to document the correct
> guidelines.
>
> Please review.
>
> Dmitri
>
> --
> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120921/1e88b46e/attachment.html>