Best Tips for documenting code using doxygen?

My team is starting to document our C code using doxygen, paying particular attention to our public API headers. There appears to be a lot of flexibility and different special commands in doxygen, which is great, but it's not clear what's a good thing and what's a bad thing without trial and error.

What are your favourite ways to mark up your code, what are your MUST DOs and DO NOTs?
**Please provide your top tips, one per answer to facilitate voting.**

I am looking to define our whole approach to API documentation, including providing a template to get the rest of the team started. So far I have something like this:

/**
* @file example_action.h
* @Author Me ([email protected])
* @date September, 2008
* @brief Brief description of file.
*
* Detailed description of file.
*/

/**
* @name Example API Actions
* @brief Example actions available.
* @ingroup example
*
* This API provides certain actions as an example.
*
* @param [in] repeat Number of times to do nothing.
*
* @retval TRUE Successfully did nothing.
* @retval FALSE Oops, did something.
*
* Example Usage:
* @code
* example_nada(3); // Do nothing 3 times.
* @endcode
*/
boolean example(int repeat);

Some commands i use in my code :

- `\todo { paragraph describing what is to be done }` Useful to keep track of todos, a page will be created in final documentation containing your todo list.
- `\c <word>` Displays the argument <word> using a typewriter font. Use this to refer to a word of code. I would use it before "TRUE" and "FALSE" in your example.
- `\a , \warning , \see` : see <http://www.stack.nl/~dimitri/doxygen/commands.html#cmdc> for description

For complex projects it may be useful to have a separate file for module management, which controls the groups and subgroups. The whole hierarchy can be in one place and then each file can simply stuff to the child groups. e.g.:

/**
* @defgroup example Top Level Example Group
* @brief The Example module.
*
* @{
*/

/**
* @defgroup example_child1 First Child of Example
* @brief 1st of 2 example children.
*/

/**
* @defgroup example_child2 Second Child of Example
* @brief 2nd of 2 example children.
*/

// @}


Simply including the definition of a group within the { } of another group makes it a child of that group. Then in the code and header files functions can just be tagged as part of whatever group they are in and it all just works in the finished documentation. It makes refactoring the documentation to match the refactor code much easier.

If you have bugs located in the code or you find bugs you can also tag in the code like this:

/** @bug The text explaining the bug */
When you then run doxygen you get a seperate Bug List alongside lists like Todo List

If you are sure your team will follow such a heavyweight template, fine, use it as shown.

Otherwise, it looks like JavaDoc. One of the nice things about Doxygen is how good a job it does *without* having to use use such strong markup. You don't need to use @name and with the JAVADOC_AUTOBRIEF setting you can skip @brief - just make sure the first line of the comment is a reasonable brief description.

I prefer descriptive names over enforcing documentation and encouraging people to add comments only when they add significant value. That way, the valuable comments aren't drowned out by all the *noise.*

If you have a really, really big project -- big enough that Doxygen runs take over an hour -- you can cut it up into multiple modules that [Doxygen later links together using tag files][1].

For example, if you have a big MSVC solution with twenty projects in it, you can make directory be its own Doxygen run, and then use tag-files to glue together the output the same way a linker glues together .libs to make an executable.

You can even take the linking metaphor more literally and make each Doxy config file correspond to a .vcproj file, so that each project (eg .lib or .dll) gets its own Doxy output.


[1]:

[To see links please register here]