doxygen_manual-1.8.1 (Методичка, задание и документация на ЛР №7), страница 8

This way the documentation can be placed in the source file instead of theheader file. This keeps the header file compact, and allows the implementer of the members more direct access tothe documentation. As a compromise the brief description could be placed before the declaration and the detaileddescription before the member definition.3.1.1.1Putting documentation after membersIf you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place thedocumentation block after the member instead of before. For this purpose you have to put an additional < markerin 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 sameare:int var; /**< Detailed description after the member */orint var; //!< Detailed description after the member//!<orint 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 memberGenerated by Doxygen22Documenting the codeorint var; ///< Brief description after the memberFor 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 sectiononly 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:\textcolor{comment}{/*! A test class */}\textcolor{keyword}{class }Test\{\textcolor{keyword}{public}:\textcolor{comment}{}\textcolor{comment}{/** An enum type.

}\textcolor{comment}{* The documentation block cannot be put after the enum! }\textcolor{comment}{*/}\textcolor{keyword}{enum} EnumType\{\textcolor{keywordtype}{int} EVal1,\textcolor{comment}{/**< enum value 1 */}\textcolor{keywordtype}{int} EVal2\textcolor{comment}{/**< enum value 2 */}\};\textcolor{keywordtype}{void} member();\textcolor{comment}{//!< a member function.}\textcolor{comment}{}\textcolor{keyword}{protected}:\textcolor{keywordtype}{int} value;\textcolor{comment}{/*!< an integer value */}\};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 commandsmentioned in the next section (like \class) are not allowed inside these comment blocks.3.1.1.2ExamplesHere is an example of a documented piece of C++ code using the Qt style:\textcolor{comment}{//! A test class.

}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{ A more elaborate class description.}\textcolor{comment}{*/}\textcolor{keyword}{class }Test\{\textcolor{keyword}{public}:\textcolor{comment}{}\textcolor{comment}{//! An enum.}\textcolor{comment}{}\textcolor{comment}{/*!\textcolor{keyword}{enum} TEnum \{TVal1, \textcolor{comment}{/*!<TVal2, \textcolor{comment}{/*!<TVal3 \textcolor{comment}{/*!<\} \textcolor{comment}{}\textcolor{comment}{//! Enum pointer.}\textcolor{comment}{}\textcolor{comment}{*enumPtr, \textcolor{comment}{}\textcolor{comment}{//! Enum variable.}\textcolor{comment}{}\textcolor{comment}{enumVar;\textcolor{comment}{}More detailed enum description.

*/}Enum value TVal1. */}Enum value TVal2. */}Enum value TVal3. */}/*! Details. */}/*! Details. */}Generated by Doxygen3.1 Special comment blocks23\textcolor{comment}{//! A constructor.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{A more elaborate description of the constructor.}\textcolor{comment}{*/}Test();\textcolor{comment}{}\textcolor{comment}{//! A destructor.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{A more elaborate description of the destructor.}\textcolor{comment}{*/}~Test();\textcolor{comment}{}\textcolor{comment}{//! A normal member taking two arguments and returning an integer value.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{\(\backslash\)param a an integer argument.}\textcolor{comment}{\(\backslash\)param s a constant character pointer.}\textcolor{comment}{\(\backslash\)return The test results}\textcolor{comment}{\(\backslash\)sa Test(), ~Test(), testMeToo() and publicVar()}\textcolor{comment}{*/}\textcolor{keywordtype}{int} testMe(\textcolor{keywordtype}{int} a,\textcolor{keyword}{const} \textcolor{k\textcolor{comment}{}\textcolor{comment}{//! A pure virtual member.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{\(\backslash\)sa testMe()}\textcolor{comment}{\(\backslash\)param c1 the first argument.}\textcolor{comment}{\(\backslash\)param c2 the second argument.}\textcolor{comment}{*/}\textcolor{keyword}{virtual} \textcolor{keywordtype}{void} testMeToo(\textcolor{keywordtype}{char} c1,\tex\textcolor{comment}{}\textcolor{comment}{//! A public variable.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{Details.}\textcolor{comment}{*/}\textcolor{keywordtype}{int} publicVar;\textcolor{comment}{}\textcolor{comment}{//! A function variable.}\textcolor{comment}{}\textcolor{comment}{/*!}\textcolor{comment}{Details.}\textcolor{comment}{*/}int (*handler)(\textcolor{keywordtype}{int} a,\textcolor{keywordtype}{int} b);\};The brief descriptions are included in the member overview of a class, namespace or file and are printed usinga small italic font (this description can be hidden by setting BRIEF_MEMBER_DESC to NO in the config file).

Bydefault the brief descriptions become the first sentence of the detailed descriptions (but this can be changed bysetting 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 isnot 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 theconfiguration file.

If you enable this option and want to put a dot in the middle of a sentence without ending it, youshould 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:\textcolor{comment}{/**}\textcolor{comment}{ * A test class. A more elaborate class description.}\textcolor{comment}{ */}\textcolor{keyword}{class }Test\{\textcolor{keyword}{public}:\textcolor{comment}{}\textcolor{comment}{/** }\textcolor{comment}{* An enum.}\textcolor{comment}{* More detailed enum description.}\textcolor{comment}{*/}Generated by Doxygen24Documenting the code\textcolor{keyword}{enum} TEnum \{TVal1, \textcolor{comment}{/**< enum value TVal1.

*/}TVal2, \textcolor{comment}{/**< enum value TVal2. */}TVal3 \textcolor{comment}{/**< enum value TVal3. */}\}*enumPtr, \textcolor{comment}{/**< enum pointer. Details. */}enumVar; \textcolor{comment}{/**< enum variable. Details. */}\textcolor{comment}{}\textcolor{comment}{/**}\textcolor{comment}{* A constructor.}\textcolor{comment}{* A more elaborate description of the constructor.}\textcolor{comment}{*/}Test();\textcolor{comment}{}\textcolor{comment}{/**}\textcolor{comment}{* A destructor.}\textcolor{comment}{* A more elaborate description of the destructor.}\textcolor{comment}{*/}~Test();\textcolor{comment}{}\textcolor{comment}{/**}\textcolor{comment}{* a normal member taking two arguments and returning an integer value.}\textcolor{comment}{* @param a an integer argument.}\textcolor{comment}{* @param s a constant character pointer.}\textcolor{comment}{* @see Test()}\textcolor{comment}{* @see ~Test()}\textcolor{comment}{* @see testMeToo()}\textcolor{comment}{* @see publicVar()}\textcolor{comment}{* @return The test results}\textcolor{comment}{*/}\textcolor{keywordtype}{int} testMe(\textcolor{keywordtype}{int} a,\textcolor{keyword}{const} \textcolo\textcolor{comment}{}\textcolor{comment}{/**}\textcolor{comment}{* A pure virtual member.}\textcolor{comment}{* @see testMe()}\textcolor{comment}{* @param c1 the first argument.}\textcolor{comment}{* @param c2 the second argument.}\textcolor{comment}{*/}\textcolor{keyword}{virtual} \textcolor{keywordtype}{void} testMeToo(\textcolor{keywordtype}{char} c1,\\textcolor{comment}{}\textcolor{comment}{/** }\textcolor{comment}{* a public variable.}\textcolor{comment}{* Details.}\textcolor{comment}{*/}\textcolor{keywordtype}{int} publicVar;\textcolor{comment}{}\textcolor{comment}{/**}\textcolor{comment}{* a function variable.}\textcolor{comment}{* Details.}\textcolor{comment}{*/}int (*handler)(\textcolor{keywordtype}{int} a,\textcolor{keywordtype}{int} b);\};Similarly, if one wishes the first sentence of a Qt style documentation block to automatically be treated as a briefdescription, one may set QT_AUTOBRIEF to YES in the configuration file.3.1.1.3Documentation at other placesIn the examples in the previous section the comment blocks were always located in front of the declaration ordefinition of a file, class or namespace or in front or after one of its members.