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

[Dmitri Gribenko]

On Fri, Sep 21, 2012 at 8:56 PM, Chandler Carruth <chandlerc at google.com> wrote:
> Ok, some comments on this:

Thank you for the reply!

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

Please see the attached patch.

> +
> +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.

Done.

> +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.

I didn't touch this area because:
1. this is not used as extensively as the basic things I tried to document;
2. clang can not yet parse declaration references in comments, so we
can only repeat what Doxygen manual says.

> +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.

Unfortunately, we don't have a good utility (except for HTML <tt> tag)
for multi-word inline code snippets.  Doxygen has some support for
markdown and thus we could use ` (backtick), but this is something
completely new to the LLVM codebase.

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

Done.

> +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.

Done.

> 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 strongly with (1) and (3).  Trailing comments in general are not bad
unless fitting comment into a single line starts to interfere with
readability and completeness.

The question is, should we add this to guidelines.

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

I tried to express these in the first paragraph.

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

I tried to reflect this in the last paragraph.

> - Suggest using '\file' markers to add the file-level comments to doxygen.

Done.

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 --------------
A non-text attachment was scrubbed...
Name: doxygen-use-in-comments-v3.patch
Type: application/octet-stream
Size: 4653 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120921/1a72993a/attachment.obj>