Computer Science > Faculty & Staff > John Winans > Documentation Standards

C and C++ Source Code Documentation Standards

When writing C and C++ applications, it is useful to follow the standards described in the Doxygen user manual when commenting your code. Doing so will allow you and your successors a way to generate a report that describes your application and how it works.

You can read about Doxygen at Wikipedia and at the Doxygen page describing how comments are processed.

For my courses, you must use the 'JavaDoc style' as discussed in the Doxygen manual using the @ for the command prefix character and a long closing comment line that looks like this:

---

/**
* This first line is a brief description.
*
* The rest of the lines are a more detailed description of the
* function that outlines what it does and anything interesting about
* how it does it.
*
* @param x Description of the first argument
* @param y Description of the second argument
* @param z Description of the third argument 
*
* @return This is where you describe the possible return values.
*
* @note This is how you can add an optional note about the function that 
*    may be of interest to someone using it.
*
* @warning This is how you can add an optional warning to a user of the 
*    function suitable for noting things like 'This function is not thread 
*    safe' and so on.
*
* @bug This is how you can add an optional description of a known bug in the
*    function such as: This only works for positive values of z.
*
*****************************************************************************/
int f(int x, int y, int z);

---

You can put your documentation in the .h or .c files but NOT BOTH. Never replicate anything! In addition to causing problems for Doxygen (see below), it will eventually become inconsistent and contradictory.

Note: When Doxygen reads your code and generates fancy documentation, it will will first look for Doxygen comments for each function declaration in your .h files and then in your .c files. When a doxygen comment is found in a .h file, it will disregard any for the same function or variable that is found in a .c file.