QOF: Useful tips for doxygen in C files

QOF 0.7.5

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

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

    -# 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 src/doc

doxywizard doxygen.cfg &