# Useful tips for doxygen in C files

## 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

### 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 &

Generated on Sat Aug 19 07:00:42 2017 for JSOC_Documentation by  1.5.7.1