If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.
Here are some examples:
int var; /*!< Detailed description after the member */
This block can be used to put a Qt style detailed documentation block after a member. Other ways to do the same are:
int var; /**< Detailed description after the member */
or
int var; //!< Detailed description after the member
//!<
or
int var; ///< Detailed description after the member
///<
Most often one only wants to put a brief description after a member. This is done as follows:
int var; //!< Brief description after the member
or
int var; ///< Brief description after the member
For functions one can use the @param command to document the parameters and then use [in], [out], [in,out] to document the direction. For inline documentation this is also possible by starting with the direction attribute, e.g.
void foo(int v /**< [in] docs for input parameter v. */);
Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.
Here is an example of the use of these comment blocks:
/*! A test class */
class Test
{
public:
/** An enum type.
* The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1, /**< enum value 1 */
int EVal2 /**< enum value 2 */
};
void member(); //!< a member function.
protected:
int value; /*!< an integer value */
};
Click here for the corresponding HTML documentation that is generated by doxygen.
WarningThese blocks can only be used to document members and parameters.
They cannot be used to document files, classes, unions, structs,
groups, namespaces and enums themselves. Furthermore, the structural
commands mentioned in the next section (like \class) are not allowed inside these comment blocks.
Examples
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 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 behavior 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. */
Here is the same piece of code as shown above, this time documented using the JavaDoc style and JAVADOC_AUTOBRIEF set to YES:
/**
* 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. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* 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.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see 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.
Similarly, if one wishes the first sentence of a Qt style documentation block to automatically be treated as a brief description, one may set QT_AUTOBRIEF to YES in the configuration file.