Throught this course you will be working on big software projects and an important part of any large project is documentation. Documentation is especially important in group projects, like many of the projects in this class. Imagine how useful a browsable index will be when your partner is asleep and you're trying to figure out his/her code. In order to ensure that your source code has adequate documentation, we will be requiring that your code be fully documented using doxygen, a documentation system for C similar to JavaDoc. This document serves as a brief overview of doxygen and the features you will use on a regular basis. For a more detailed description of doxygen and all of its features visit the doxygen homepage. You can get for detailed documentation and information compiling and installing doxygen on a home system.
There are two types of comments we want in your code. The first kind are comments at the beginning of each file which describes the file the file and lists things like author and known bugs. The second kind of comments are those that describe your functions and data structures. We want you to put comments on all your functions and data structures. You do not have to comment individual variable instances but are welcome to if you'd like. The rest of this document talks about the doxygen commands that you need for each of the two kinds. First, we'll describe what we expect to see and then talk about the specific commands that you need to use including simple examples. Lastly there will be a larger example showing all of commands together.
Each file needs to begin with the @file command stating the name of the file. This should be followed by a brief description of the file using the @brief command. If necessary, you can follow this with a more detailed description. Next you should put your name and andrew id, along with your partners name and andrew id, using the @author tag. This needs to be followed with a bugs section with a list of known bugs using the @bug command. If there are no known bugs, explicitly state that using the @bug command.
Before each function, data structure, and macro you should put a comment block giving at least a brief description using the @brief command. A brief description will suffice for your data structures but for you macros and functions you will need to use a few more commands. After your description, you should use the @param command to describe all of the parameters to your function. These descriptions should be followed by a description of the return value using the @return command.
You can choose to comment your functions either in the header files where they are declared (prefered) or in the source files where they are implemented or both. If you choose to put the comments in both places note that if there is a difference between the two sets of comments, the block at the declaration will superceed the one at the implementation. As a further note, doxygen does not parse assembly language files. Therefore, your documentation for functions implemented in assembly language files should only be described in the header files where they are declared.
All commands in the documentation start with a backslash (\) or an at-sign (@). If you prefer you can replace all commands starting with an at-sign below, by their counterparts that start with a backslash.
Some commands have one or more arguments. Each argument has a certain range:
If [square] brackets are used the argument is optional.
Indicates that a comment block contains documentation for a source or header file with name <name>. The file name may include (part of) the path if the file-name alone is not unique. If the file name is omitted (i.e. the line after @file is left blank) then the documentation block that contains the @file command will belong to the file it is located in.
/** @file file.h * @brief This is an example file. * * This file shows how to use the file command. */Click here for the corresponding html document that is created by doxygen.
Starts a paragraph that serves as a brief description. For classes and files the brief description will be used in lists and at the start of the documentation page. For class and file members, the brief description will be placed at the declaration of the member and prepended to the detailed description. A brief description may span several lines (although it is advised to keep it brief!). A brief description ends when a blank line or another sectioning command is encountered. If multiple @brief commands are present they will be joined.
/** @file file.h * @brief This is an example file. * * This file shows how to use the briefcommand. */ #ifndef __FILE_H #define __FILE_H /** @brief This is the brief description. * It can span multiple lines. * * This is where the full description goes. */ void function(); #endif __FILE_HClick here for the corresponding html document that is created by doxygen.
Starts a paragraph where one or more author names may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent @author commands will be joined into a single paragraph and separated by commas. Alternatively, one @author command may mention several authors. The @author command ends when a blank line or some other sectioning command is encountered.
/** @file file.h * @brief This is an example file. * * This file shows how to use the author command. * @author Fred Hacker (fhacker) * @author Harry Q. Bovik (hqbovik) */Click here for the corresponding html document that is created by doxygen.
Starts a paragraph where one or more bugs may be reported. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent @bug commands will be joined into a single paragraph. Each bug description will start on a new line. Alternatively, one @bug command may mention several bugs. The @bug command ends when a blank line or some other sectioning command is encountered.
/** @file file.h * @brief This is an example file. * * This file shows how to use the bug command. * @bug This is the first bug. * @bug Another bug! */Click here for the corresponding html document that is created by doxygen.
Starts a parameter description for a function parameter with name <parameter-name>. Followed by a description of the parameter. The existence of the parameter is not checked. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent @param commands will be joined into a single paragraph. Each parameter description will start on a new line. The @param description ends when a blank line or some other sectioning command is encountered.
/** @file file.h * @brief This is an example file. * * This file shows how to use the param command. */ #ifndef __FILE_H #define __FILE_H /** @brief This function does nothing. * * @param do an integer telling it what to do * @param nothing a character telling it nothing */ void do_nothing(int do, char nothing); #endif __FILE_HClick here for the corresponding html document that is created by doxygen.
Starts a return value description for a function. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent @return commands will be joined into a single paragraph. The @return description ends when a blank line or some other sectioning command is encountered.
/** @file file.h * @brief This is an example file. * * This file shows how to use the return command. */ #ifndef __FILE_H #define __FILE_H /** @brief This macro returns the maximum of two numbers. * * @param a the first number * @param b the second number * @return the maximum of a and b */ #define MAX(a, b) ((a) > (b)) ? (a) : (b) #endif __FILE_HClick here for the corresponding html document that is created by doxygen.
Here is a short example showing all the elements together.
/** @file file.h * @brief This is an example file. * * This file shows how to use all the commands described. * @author Joey Echeverria (jge) * @bug The MIN() macro appears to be broken. */ #ifndef __FILE_H #define __FILE_H /** @brief This macro returns the maximum of two numbers. * * @param a the first number * @param b the second number * @return the maximum of a and b */ #define MAX(a, b) ((a) > (b)) ? (a) : (b) /** @brief This macro returns the minimum of two numbers. * * @bug This macro doesn't work. * @param a the first number * @param b the second number * @return the minimum of a and b */ #define MIN(a, b) ((a) > (b)) ? (a) : (b) /** @brief This function does nothing. * * @param do an integer telling the function what to do * @param nothing a character telling the function nothing * @return void */ void do_nothing(int do, char nothing); #endif __FILE_HClick here for the corresponding html document that is created by doxygen.
Permission to use, copy, modify, and distribute this documentation under the terms of the GNU General Public License is hereby granted. No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. See the GNU General Public License for more details.
Portions of this document Copyright © 1997-2003 by Dimitri van Heesch