Using Doxygen in the NWChemEx Project
The purpose of this page is to give you a (likely less than 10 minute) primer on how to use Doxygen particularly with respect to the NWChemEx project. The NWChemEx project uses Doxygen to document C++ code. For documenting Python or writing documentation pages like this one the project uses Sphinx’s ReST flavor.
Intro To Doxygen
Doxygen allows you to document your C++ code in a minimally invasive manner. It does this by requiring you to write your C++ comments using Doxygen’s markup language. Bare-bones this looks like:
/// This is a Doxygen, single-line comment for the following function
void function1();
/** For more extened documentation block comments are preferred.
*
* This line is also part of the comment.
*/
void function3();
Doxygen supports other conventions; however, the two above are the approved conventions for the NWChemEx project. For consistency please use them.
Doxygen has two types of comments: brief and detailed. Brief comments are
primarily used to give a reader a quick, one-line summary of a function, class,
etc.. By convention single line comments are always briefs, whereas the first
line (up to the first period)of a multi-line comment is the brief and the
remaining lines are the detailed description. When making multi-line comments
it is good practice to start the brief with @brief. This will ensure that
the brief continues until the first blank line and will prevent surprises from
forgetting the period convention. @brief is an example of a Doxgyen keyword.
Keywords are signaled by the @ symbol (there’s another convention too, but
this is the one approved for NWChemEx) and have a special meaning to Doxygen.
There’s a lot of
keywords and the
next section acquaints you with the minimum set of keywords that you must use
when documenting C++ code for use with NWChemEx.
Minimal Documentation Standards
By far the most useful keywords are shown in the following code example. For documenting a function this should be considered as a minimal acceptable amount of documentation. For documenting data members and types a single line comment is often fine (just describing what it is).
/** @brief This is the brief description of fake function 1.
*
* Fake function 1 demonstrates the bare minimal documentation standards.
* What you are currently reading, is the detailed description that will
* show up in the documentation. The "*" border is optional, but
* encouraged.
*
* @tparam T The type this function takes. The documentation should tell
* you what concept it satisfies.
* @param[in] Param1 The first parameter; it's read-only.
* @param[out] Param2 The second parameter; it's going to be written to.
* @param[in,out] Param3 The third parameter; it's going to be read from
* and written to.
* @returns Whatever this function returns.
*
* @throws std::runtime_error Tell you when it throws and what exception
* guarantee is afforded.
*/
template<typename T>
int function1(int Param1, int& Param2, int& Param3);
Obviously the real documentation should be more helpful, but this illustrates
the key things to document: brief, detailed description, input/output
parameters, return value, template type (or non-type) parameters, and
exceptions that are thrown (as well as the level of exception guarantee).
Other useful commands to be aware of:
@filefor documenting files (particularly useful for files containing many functions)@defgroupused to define groups for organizational reasons@ingroupfor associating a file, class, member, etc. with a particular group@f$<latex here> @f$for adding on line Latex formulae@f{eqnarray}{for starting a Latexeqnarray(change the environment name to get other environments), this environment is ended by@f}@notefor starting a note@warningfor displaying a warning to the reader@bugfor letting the reader know about a known bug@relatesfor free-functions associated with a particular class