Chapter II: Documenting The Code
Special notes
A special note is a C / C comment block with additional marks so that Doxygen knows that it is necessary to add it to the document.
There are two comments for each code block, which consists of documents: one is a brief description of the Detailed description, all optional. There can be more than one BRIEF description and Detailed description, but it is invalid.
As the name suggests, a Brief description is only one line, and the Detail description is a longer and more detailed document.
There are several ways to add a Detail description:
1. Using the Javadoc style, contain a C style annotation block
/ **
* ... text ...
* /
2. Use the QT style
/ *!
* ... text ...
* /
This is optional, so
/ *!
... Text ...
* /
Also effective
3. The third style is at least two C notes, plus one per line / or!
///
/// ... Text ...
///
or
//!
//! ... Text ...
//!
4. Some people like to become more eye-catching, which can be made
/
/// ... Text ...
/
Add BRIEF notes
1. One is to use / brief in the above note block, then follow the Detail Comment after a blank line
/ *! / brief brief description.
* Brief Description Continued.
*
* Detailed description starts here.
* /
2. If javadoc_autobrief is set to YES in the configuration file, use the Javadoc Style Comment Block to start a brief comment, this comment will end with one space or new line.
/ ** Brief Description Which Ends at this Dot. Details Follow
* Here.
* /
Also can be applied to multi-line C style comments
/// brief description Which Ends at this Dot. Details Follow
/// here.
3. The third can use a special C style annotation, no more than one line each time
/// brief description.
/ ** Detailed description. * /
or
//! Brief descriphen.
//! Detailed Description
//! Starts here.
Note the empty line in the latter example, Doxygen uses him to separate the Brief description and Detail description. In this case, javadoc_autobrief should also be set to No
As you can see, Doxygen is very flexible, and this way of writing is illegal.
//! Brief Description, Which IS
//! really a detailed description Since It Spans Multiple Lines.
/ *! OOPS, ANOTHER DETAILED DESCRIPTION!
* /
Because Doxygen only allows a Brief and a Detail description
Further, if a Brief describes before the Declaration, one of the Declaration is used before Code. This is also the case for Detailed description, and the one before definition is high priority before Declaration.
Here is a QT style C example: (Note this section needs to be carefully studied, rewrite the code to remove the release macro) //! A Test class.
/ *!
A More Elaborate Class Description.
* /
Class test
{
PUBLIC:
//! An enum.
/ *! More detailed enum description. * /
ENUM TENUM {
TVAL1, / *! TVAL2, / *! TVAL3 / *! } //! Enum Pointer. / *! Details. * / * ENUMPTR, //! Enum variable. / *! Details. * / Enumvar; //! A constructor. / *! A More Elaborate Destription of the Constructor. * / Test (); //! A destructor. / *! A More Elaborate Destructor. * / ~ Test (); //! A Normal Member Taking Two Arguments and return an integer value. / *! / Param a an integer argument. / param s a constant character Pointer. / returnid / 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); } These single-line annotations include a BRIEF description, and the Multi-Line comment block contains a more detailed description. The Brief describes the preview of the MEMBER of Class, Namespace, or File, the slope of the small number (by setting BRIEF_MEMBER_DESC to NO). The default Brief description is the first sentence described in DetaileD (changing this setting by setting the REPEAT_BRIEF to NO). Bout and Detailed are optional in the QT style. Default, Javadoc style annotation blocks and QT style annotations are equally valid. This is not based on the Javadoc specification, but the first line of comments is considered to be a brief description. To open this setting, set javadoc_autobrief to YES. Use one "." To separate, or use a "/": / ** brief description (E.g./ useing only a few words). Details FOLLOW. * / Set Javadoc Style and Javadoc_autobrief for YES: / ** * A Test class. A more elaborate class description. * / Class test { PUBLIC: / ** * An enum. * More Detailed Enum Description. * / ENUM TENUM { TVAL1, / ** TVAL2, / ** TVAL3 / ** } * enumptr, / ** Enumvar; / ** / ** * A Constructor. * A more elaborate Destription of the constructor. * / Test (); / ** * A destructor. * A more elaborate Destription of the destructor. * / ~ Test (); / ** * a Normal Member Taking Two Arguments & Return 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); } And most document systems are different, doxygen also allows you to put Member notes before definition. In this way, the comment can be written in the .cpp file instead of .h file. This file is relatively simple, while MEMBER is directly annotated. As a compromise, the Brief description can be placed before the Declaration of MEMBER, and the Detailed description can be placed before definition.
