[asterisk-dev] Doxygen documentation

[Russell Bryant]

snuffy wrote:
> 1. Using \retval instead of return to make it easier to read in code 
> (shame doxygen puts it all together when parsing it to be in html)

I like it.

> 2. For documentation of '__functions' we add just \see 'function' since it should be documented at the .h level and that way when people browse the documentation they can click to get the actual full description rather than 
>  creating clutter in the .c doxygen can't understand that the __ version 
> and normal link.This can reduce duplication and clutter when viewing the 
> source itself.
> 
> For example res_crypto .c I would just add the following
> 
> /*!
> * \brief return the ast_key structure for name
> * Check .h for full documentation
> * \see ast_key_get
> */
> static struct ast_key *__ast_key_get(const char *kname, int ktype)

This sounds good, as well.

> 3. If anyone could help me understand the \ref errors in 'make progdocs' 
> and how i could go about fixing them let me know.

I haven't generated them manually in a while, since I usually just go look at 
the ones on asterisk.org.  If there are some errors that you are getting that 
you're not sure about, feel free to post them to this list, and we'll figure it out.

> 4. If all doxygen comments for variables must be in the form of /*! */ 
> before a variable is declared and replacing all /*!< */ instances that 
> can be done.

Other people may have different opinions on this, but I certainly agree.  I very 
much prefer having the doxygen comment in the /*! */ (before the variable) form 
instead of /*!< */ (afterwords, inlined).  This is mostly because it tends to 
encourage better documentation, since it's more pleasant to make multiline 
comments when they go before the variable.  However, I'm not sure this is worth 
changing for the ones that exist, unless the actually contents of the comments 
are being improved, as well.

-- 
Russell Bryant
Software Engineer
Digium, Inc.