Alex Rivera | Logout

Best Tips for documenting code using doxygen?

Asked 2008-09-09T11:41:38.193
308

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 (me@example.com)
 * @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);
c++ c documentation doxygen
Edit
Report

2 Answers

49

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 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
answered 2008-09-09T13:39:12.827
4

If you are worried that some team members will avoid documenting or you just want a working minimal sets of documentation, you can enable these in your doxygen configuration. 

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES

As part of your doxygen build process save the warnings to a file and try to get and keep the warning count as low as possible (0 if that is reasonable). If you do this, every public and protected class member will need at least an @brief, @param for each function argument and an @return. This is good enough to describe most APIs and not too much to encumber other living codebases.

You should, of course, encourage people to document as much as they feel is required on a case by case basis, as long as they meet the minimum project standards. Don't set the minimum too high though, then you may not get useful documentation in the end.

For example, in our project, everything another coder is likely to touch should be documented. Enabling the warnings let see how close that goal we are. We also try to use @internal to describe what/why we do what we do with some of our private members.

answered 2011-01-23T23:08:24.170

Your Answer