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

[Sean Silva]

Hi Dmitri, please make sure that you actually build the Sphinx docs
with the patch applied, as the current patch has a number of errors
which prevent it from rendering correctly. To do that, cd into docs/,
then run the command `make -f Makefile.sphinx html` and then open
docs/_build/html/CodingStandards.html in your web browser to make sure
that everything is being rendered correctly.

In particular, Sphinx is really finicky about having blank lines in
certain places, such as before and after `.. code-block:: c++`. Your
current patch which your current patch is omitting these blank lines
in a number of places.

Let me know if you have any questions about how to use Sphinx or
reStructuredText. I'm actually in the process of writing up a "how to
write docs with sphinx" document and if you want I can post it.

--Sean Silva

On Fri, Sep 21, 2012 at 3: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.
>
> 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>*/