Simple Doxygen templates

This is a follow-up to previous tutorial, Simple guide to basic Doxygen usage.

Here are few simple templates that you might use for documenting your source; easiest use is with e.g. Visual Assist X, or any other tool that allows you to add predefined templates to your source code. I use these template with VAX and shortcut set to “/*!”, with short descriptive names, thus I don’t need to remember many shortcuts and have all at reach of 3 key-clicks. 😀

And we finish off with a small list of simple tips.

General Doxygen comment block

This is a simple comment block, with both brief and detailed sections:

//!
/*!
 *
 */

In VAX, you can use following template:

//! $end$
/*!
 *
 */

File header comment block

This is a simple comment block to use as a file header:

/*!
 * \file [filename]
 *
 * \author [your name]
 * \date
 *
 * [your comment here]
 */

In VAX:

/*!
 * \file $FILE_BASE$.$FILE_EXT$
 *
 * \author [your name]
 * \date $MONTHLONGNAME$ $YEAR$
 *
 * $end$
 */

Class comment block

/*!
 * \class [class name]
 *
 * \brief [brief description]
 *
 * [detailed description]
 *
 * \author [your name]
 * \date
 */

In VAX:

/*!
 * \class $end$
 *
 * \brief
 *
 *
 *
 * \author [your name]
 * \date $MONTHLONGNAME$ $YEAR$
 */

Function comment block

/*!
 * \brief [brief description]
 *
 * [detailed description]
 *
 * \param[in] [name of input parameter] [its description]
 * \param[out] [name of output parameter] [its description]
 * \return [information about return value]
 * \sa [see also section]
 * \note [any note about the function you might have]
 * \warning [any warning if necessary]
 */

In VAX:

/*!
 * \brief
 *
 * $end$
 *
 * \param[in]
 * \param[out]
 * \return
 * \sa
 * \note
 * \warning
 */

Few more tips

Doxygen allows you to format the documentation in many ways, e.g. you can use html mark-up in comments, add LaTeX equations (via the \f$ command, or the the \f[ , \f] command pair), add diagrams, and much more.

“Paired commands”

What you have to pay attention to are the paired commands. Doxygen, thanks to the general nature of documentation you can produce, allows you to make many mistakes without informing you about them. At best, you get a message of a style “reference to undocumented symbol”, and you’ll be wondering why, when the symbol is (in your opinion) documented.

So, here’s a list of commands that you should use carefully, more precisely you should always “close them”! :

\code, \endcode … inserts block of code into documentation
\dot, \enddot … inserts description of a dot graph
\msc, \endmsc … inserts description of a message sequence chart
\htmlonly, \endhtmlonly … inserts block of text that will be verbatim included in the generated HTML documentation only (e.g. JavaScript)
\latexonly, \endlatexonly … inserts block of text that will be verbatim included in the generated LaTeX documentation only
\manonly, \endmanonly … inserts block of text that will be verbatim included in the generated MAN documentation only
\verbatim ,\endverbatim … inserts block of text that will be verbatim included in both the HTML and the LaTeX documentation
\xmlonly, \endxmlonly … inserts block of text that will be verbatim included in the generated XML output only
\f$, \f$ … though the same, have to come in pair; inserts an in-text (LaTeX) formula; e.g. \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$
\f[, \f] … inserts a long (LaTeX) formula that is displayed centered on a separate line

That’s about it… There are 2 or 3 more, but these are those you’ll use most. Just remember – close your blocks, and you won’t get any of those weird errors. 🙂

Section commands

Then, there are various sections you might use in your documentation; some we saw above, here’s a list:

\attention … paragraph where a message that needs attention may be entered
\author … paragraph where one or more author names may be entered
\brief … paragraph that serves as a brief description
\bug … paragraph where one or more bugs may be reported
\date … paragraph where one or more dates may be entered
\deprecated … paragraph indicating that this documentation block belongs to a deprecated entity
\details … starts the detailed description; if you leave a blank line after \brief, this command is not needed (see above, it’s nowhere 😉 )
\exception <exception-object> or \throw <exception-object> … exception description for an exception object with name <exception-object>, followed by a description of the exception
\invariant … paragraph where the invariant of an entity can be described
\note … paragraph where a note can be entered
\par [(paragraph title)] … if a paragraph title is given this command starts a paragraph with a user defined heading
\param <parameter-name> … parameter description for a function parameter with name <parameter-name>;; multiple adjacent \param commands will be joined into a single paragraph; direction of the attribute may be specified:

\param[in] param1 Description
\param[out] param1 Description
\param[in,out] param1 Description

\remarks … paragraph where one or more remarks may be entered
\return … return value description for a function
\retval <return value> … return value description for a function with name <return value>
\sa or \see … paragraph where one or more cross-references to classes, functions, methods, variables, files or URL may be specified; two names joined by either :: or # are understood as referring to a class and one of its members; one of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name
\since … used to specify since when (version or time) an entity is available
\test … paragraph where a test case can be described
\todo … paragraph where a TODO item is described
\version … paragraph where one or more version strings may be entered
\warning … paragraph where one or more warning messages may be entered

Visual enhancement commands

And finish off this list, commands for visual enhancements:

\a <word> … displays <word> using a special font; use this command to refer to member arguments in the running text: computes sum of \a x and \a y
\arg … can be used to generate a simple, not nested list of arguments; each item continues until the first blank line or until another \arg is encountered
\b <word> … displays <word> using a bold font; to put multiple words in bold, use html’s <b>some text</b>
\c <word> or \p <word> … displays <word> using a typewriter font, eq. to html’s <tt>some text</tt>
\e <word> or \em <word> … displays <word> in italics
\n … forces new line, eq. to <br>
\\ … writes a backslash character (\) to the output; backslash has to be escaped because doxygen uses it to detect commands
\@ … writes an at-sign (@) to the output; at-sign has to be escaped because doxygen uses it to detect JavaDoc commands
\& … writes & to the output
\$ … writes $ to the output
\# … writes # to the output
\< … writes < to the output
\> … writes > to the output
\% … writes % to the output

For more details see Doxygen documentation, or better yet – try them all out!

4 responses to “Simple Doxygen templates

  1. Pingback: Doxygen useful info – Celal SAVUR

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s