Special documentation blocks for doxygen
A special documentation block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of documentation that needs to end up in the generated documentation. For Python and VHDL code there are a different comment conventions, which can be found in section Special documentation blocks in Python and Special documentation blocks in VHDL respectively.
For each code item there are two (or in some cases three) types of descriptions, which together form the documentation: a brief description and detailed description, both are optional. For methods and functions there is also a third type of description, the so called "in body" description, which consists of the concatenation of all comment blocks found within the body of the method or function.
Having more than one brief or detailed description is allowed (but not recommended, as the order in which the descriptions will appear is not specified).
As the name suggest, a brief description is a short one-liner, whereas the detailed description provides longer, more detailed documentation. An "in body" description can also act as a detailed description or can describe a collection of implementation details. For the HTML output brief descriptions are also use to provide tooltips at places where an item is referenced.
There are several ways to mark a comment block as a detailed description:
-
You can use the JavaDoc style, which consist of a C-style comment block starting with two *'s, like this:
/** * ... text ... */
-
or you can use the Qt style and add an exclamation mark (!) after the opening of a C-style comment block, as shown in this example:
/*! * ... text ... */
In both cases the intermediate *'s are optional, so
/*! ... text ... */
is also valid.
-
A third alternative is to use a block of at least two C++ comment lines, where each line starts with an additional slash or an exclamation mark. Here are examples of the two cases:
/// /// ... text ... ///
or
//! //!... text ... //!
Note that a blank line ends a documentation block in this case.
-
Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:
/********************************************//** * ... text ***********************************************/
(note the 2 slashes to end the normal comment block and start a special comment block).
or
///////////////////////////////////////////////// /// ... text ... /////////////////////////////////////////////////
For the brief description there are also several posibilities:
-
One could use the /brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.
Here is an example:
/*! /brief Brief description. * Brief description continued. * * Detailed description starts here. */
-
If JAVADOC_AUTOBRIEF is set to
YESin the configuration file, then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. Here is an example:/** Brief description which ends at this dot. Details follow * here. */
The option has the same effect for multi-line special C++ comments:
/// Brief description which ends at this dot. Details follow /// here.
-
A third option is to use a special C++ style comment which does not span more than one line. Here are two examples:
/// Brief description. /** Detailed description. */
or
//! Brief descripion. //! Detailed description //! starts here.
Note the blank line in the last example, which is required to separate the brief description from the block containing the detailed description. The JAVADOC_AUTOBRIEF should also be set to
NOfor this case.
As you can see doxygen is quite flexible. If you have multiple detailed descriptions, like in the following example:
//! Brief description, which is //! really a detailed description since it spans multiple lines. /*! Another detailed description! */
They will be joined. Note that this is also the case if the descriptions are at different places in the code! In this case the order will depend on the order in which doxygen parses the code.
Here is an example of a documented piece of C++ code using the Qt style:
//! A test class. /*! A more elaborate class description. */ class Test { public: //! An enum. /*! More detailed enum description. */ enum TEnum { TVal1, /*!< Enum value TVal1. */ TVal2, /*!< Enum value TVal2. */ TVal3 /*!< Enum value TVal3. */ } //! Enum pointer. /*! Details. */ *enumPtr, //! Enum variable. /*! Details. */ enumVar; //! A constructor. /*! A more elaborate description of the constructor. */ Test(); //! A destructor. /*! A more elaborate description of the destructor. */ ~Test(); //! A normal member taking two arguments and returning an integer value. /*! /param a an integer argument. /param s a constant character pointer. /return The test results /sa Test(), ~Test(), testMeToo() and publicVar() */ int testMe(int a,const char *s); //! A pure virtual member. /*! /sa testMe() /param c1 the first argument. /param c2 the second argument. */ virtual void testMeToo(char c1,char c2) = 0; //! A public variable. /*! Details. */ int publicVar; //! A function variable. /*! Details. */ int (*handler)(int a,int b); };
Click here for the corresponding HTML documentation that is generated by doxygen.
The one-line comments contain a brief description, whereas the multi-line comment blocks contain a more detailed description.
The brief descriptions are included in the member overview of a class, namespace or file and are printed using a small italic font (this description can be hidden by setting BRIEF_MEMBER_DESC to NO in the config file). By default the brief descriptions become the first sentence of the detailed descriptions (but this can be changed by setting the REPEAT_BRIEF tag to NO). Both the brief and the detailed descriptions are optional for the Qt style.
By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block. This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description. To enable this behaviour you should set JAVADOC_AUTOBRIEF to YES in the configuration file. If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it. Here is an example:
/** Brief description (e.g./ using only a few words). Details follow. */