怎样注释C/C++代码

简述(brief description)和详述(detailed description)

详述的几种方式

1. JavaDoc style

/**

* ... text ...

*/

2. Qt style
/*!

* ... text ...

*/

3. C++ comment style    ///

/// ... text ...

///

or

//!

//! ... text ...

//!

4. Block style    /********************************************//**

*  ... text

***********************************************/

(note the 2 slashes to end the normal comment block and start a special comment block).

or     /////////////////////////////////////////////////

/// ... text ...

////////////////////////////////////////////////

简述的几种方式

1. /brief

command

/*! /brief Brief description.

*         Brief description continued.

*

*  Detailed description starts here.

*/

2. 设置JAVADOC_AUTOBRIEF
， 第一句作为描述
/** Brief description which ends at this dot. Details follow

*  here.

*/

3. C++ style      /// Brief description.

/** Detailed description. */

or    //! Brief descripion.

//! Detailed description

//! starts here

示例， 使用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);
};

JavaDoc style, 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);
};

参考 http://www.stack.nl/~dimitri/doxygen/docblocks.html