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

[Dmitri Gribenko]

On Fri, Sep 21, 2012 at 10:25 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> 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.

This version of the patch also updates all other documentation
comments in coding standards to conform to the proposed Doxygen
guidelines.

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-v5.patch
Type: application/octet-stream
Size: 6686 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120926/b2cc3cee/attachment.obj>