Re: Doxygen comments in code

[Richard Andrews <richarda at ixla dot com dot au>]

At my work we have a standard header for every function that we tack on the
front with a simple cut and paste. It has a @brief, @param, @note, @pre and
@post. Each file has a @file section and a @class section for each class
that is declared in it. It's then (usually) a simple matter to fill in a
lot of the text with sed or perl scripts.

Providing a standard template for everyone to use would speed things up;
just cut and paste the block and fill in the details or remove unused
sections.

We generally only add the blocks to implementation areas to avoid clutter
in class declarations. Of course this is sometimes unavoidable in templated
classes if the implementation is in the declaration.

I consider a @brief section essential for each class, and function as this
text will be shown in the summary of the class. A long explanation is often
not necessary unless the behaviour has many different possibilities that
all need to be explained. @param is good to emphasize units being passed
(eg. is the size passed in bits, bytes or blocks) but probably isn't
mandatory.

@pre and @post are useful to help track down unusual behavioural
requirements when debugging.

One thing that I have found useful is to have a @class or @fn line that
explicitly attaches a doc block to a function. The reason being that if
code is cut and pasted somewhere and the doc is left behind (accidentally)
two things occur 

(a) doxygen will still attach the doc to the correct function/class 

(b) maintainers can instantly determine what piece of code the dismembered
documentation belongs to and move it as appropriate.


> To that end, I'm soliciting opinions on what we should document for each
> public class, variable, and function.  Just an overview?  Each parameter?
> Something in between those two?  Keep in mind that we can release an
> encyclopedia if we want for 3.1.  Also keep in mind that the more we want
> documented, the more help I'll need (my wrists get sore enough from
> typing
> already :-).
> 
> Initially I'd like to drop placeholder text in everywhere we plan on
> documenting for 3.0; that way people can easily see whether a particular
> thing has been documented yet or not.  Contributors then don't have to
> ask where/what/whether a thing should be documented.
>