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

[Sean Silva]

Ping. (not my patch, but I think this is important and seems to have
gotten lost in the list).

-- Sean Silva

On Wed, Sep 26, 2012 at 3:14 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> 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>*/