Useful tips for doxygen in C files

• Doxygen reference documentation The Doxygen manual

An introduction to doxygen markup

What to document

All declarations for:

1. typedef
2. struct
3. enum
4. functions

This will enable doxygen to link all parameter types to the declarations every time the type is used in a function - very helpful to new developers.

Private files

If your declarations are in separate files, like private header files, a simple block can still be linked into doxygen as long as the file is identified to doxygen using a '\file' section:

\file filename.h
\brief one-liner summary of the file purpose
\author the usual copyright statement

How to document

Every doxygen comment block starts with an adapted comment marker. You can use an extra slash /// or an extra asterisk. Blocks end in the usual way. Doxygen accepts commands using a backslash.

To put a description with each function or structure, use '\brief' End the brief description with a blank line. The rest of the documentation will then be shown in the body of the doxygen page.

Commands may begin with \ or @

Extras

1. Start a line with a hyphen to start a list - the indent determines the nesting of the list:
   • To create a numbered list, use -# e.g. for a sublist:
     1. start a numbered list
   • revert to previous list

End the list with a blank line. Use :: at the start of a function or structure to link to the page for that function in the doxygen documentation. e.g. qof_class_foreach

Use the param command to describe function parameters in the text.

Use the 'back reference' to document enumerator values:
enum testenum {
enum_one **< less than marker tells doxygen to use this line to document enum_one.

Editing Doxygen configuration

To edit the doxygen configuration, you can use:

cd doc

vi doxygen_publ.cfg &