Useful tips for doxygen in C files

Hacking on this documentation

There is the beginning of a style guide for documenting under Useful tips for doxygen in C files.

The Book Merge files are an attempt to document "by the book". Merging QofBook structures
Feel free to start documenting or playing with doxygen configuration. This main page can be found in src/doc/doxygen_main_page.c .

Each doxygen section must be within a single comment block although large comment blocks can be split into separate pages: Style discussion.

This main page is just an introduction to doxygen markup, see the Doxygen manual for the full command set.

• Useful tips for doxygen in C files Tips and hints for using doxygen
• Style discussion Long comments, pages, editors
• Doxygen reference documentation Links to the Doxygen manual

Code snippets need special handling in the text overviews. Change all comment markers to // (so that the overview comment remains intact) and then wrap each code snippet in the verbatim endverbatim doxygen markers.

One useful method is to edit these .txt files using the syntax highlighting of normal C files.

• GnuCash design and developer's reference Introduction
• Style discussion Long comments, pages, editors
• 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 src/doc

doxywizard doxygen.cfg &