[asterisk-dev] Doxygen documentation

[snuffy]

Hello All,

I've been looking at the doxygen and want to try and standardise it a little
bit more.
Here are my suggestions:
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)
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)

3. If anyone could help me understand the \ref errors in 'make progdocs' and
how i could go about fixing them let me know.
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.

I'm open for suggestions on how to proceed

-Brad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-dev/attachments/20070710/1eca019e/attachment.htm