第二章：Documenting the code
特殊的注释
一种特殊的注释是带有一些额外标记的C/C++注释块，这样doxygen就知道需要将其加入到文档中了。
对于每个代码块都有两种注释，这两种注释组成了文档：一种是brief 描述另一种是detailed 描述，都是可选的。可以有多于一个的brief 描述和detailed 描述，但是是无效的。
顾名思义，一个brief描述只有一行，而detail描述则是更长更详尽的文档。
有几种方式添加一个detail描述：
1. 使用JavaDoc风格，包含一个C风格的注释块
/**
* ... text ...
*/
2. 使用Qt风格
/*!
* ... text ...
*/
这中间的*都是可选的，因此
/*!
... text ...
*/
也是有效的
3. 第三种风格是至少使用两个C++注释行，每行加多一个/或者是!
///
/// ... text ...
///
或
//!
//!... text ...
//!
4. 有些人喜欢将注释变得比较醒目，可以这样来作
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
有以下方式添加brief注释
1. 一种是在上述注释块中使用/brief，然后一个空行后跟着Detail注释
/*! /brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
2. 如果配置文件中JAVADOC_AUTOBRIEF被设为YES，则使用JavaDoc风格注释块将自动开始一个brief注释，这个注释将以“.”后跟一个空格或新行结束
/** Brief description which ends at this dot. Details follow
* here.
*/
同样可以应用到多行的C++风格注释中
/// Brief description which ends at this dot. Details follow
/// here.
3. 第三种可以使用一种特殊的C++风格注释，每次不超过一行
/// Brief description.
/** Detailed description. */
或
//! Brief descripion.
//! Detailed description
//! starts here.
注意后一个例子中的空行，Doxygen用他来分开brief描述和detail描述。在此情况下JAVADOC_AUTOBRIEF也应设置为NO
如你所见，doxygen很灵活，下面这种写法是非法的
//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Oops, another detailed description!
*/
因为doxygen只允许一个brief和一个detail描述
更进一步，如果一个brief描述在 declaration前，一个在code前，那么将使用declaration前的那个。对于detailed描述也是如此，definition前的那个比declaration前的有高优先级。
这里有一段Qt风格的C++例子：（注意这一段需要仔细研究，改写掉注释宏的代码）
//! 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 return 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);
};
这些单行注释包括一个brief描述，而multi-line注释块包含一个更详细的描述。
Brief描述包含在class，namespace或file的member的预览中，小号的斜体字（通过将BRIEF_MEMBER_DESC设置为NO可以关掉这些brief描绘）。缺省的brief描述是detailed描述的第一句话（通过将REPEAT_BRIEF设置为NO可以改变此设置）。在Qt风格中brief和detailed都是可选
缺省的，JavaDoc风格的注释块和Qt风格的注释同样有效。这并不是根据JavaDoc规格的，而是注释的第一行被认为是brief描述。要打开此设置，将JAVADOC_AUTOBRIEF设置为YES。用一个“.”来作分隔，或者使用一个“/”：
/** Brief description (e.g./ using only a few words). Details follow. */
设置JavaDoc style和JAVADOC_AUTOBRIEF为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 & 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);
};
和大多数文档系统不一样，doxygen也允许你将将member注释放在definition之前。这种方式下，注释可以写在.cpp文件中而非.h文件中。这样头文件就显得比较简洁，同时member前也直接有注释。作为一种妥协，brief描述可以放在member的declaration前，detailed描述可以放在definition前。
Trackback: http://tb.blog.csdn.net/TrackBack.aspx?PostId=21949