常用注釋語法

• 注釋寫在對應(yīng)的函數(shù)或變量前面。JavaDoc類型的多行注釋風(fēng)格如下：

/** * 這里為注釋. */

• 一般注釋中有簡要注釋和詳細(xì)注釋，簡要注釋有多種標(biāo)識方式，這里推薦使用@brief命令強(qiáng)制說明，例如：

/** * @brief 這里為簡要注釋. * * 這里為詳細(xì)注釋. */

• @brief之后為簡要注釋，簡要注釋結(jié)束的標(biāo)志是一個(gè)點(diǎn)號，或一個(gè)空行。簡要注釋之后的注釋為詳細(xì)注釋，因此也可以寫成：其中\(zhòng)n為換行符。

/** * @brief 簡要注釋. 詳細(xì)注釋. \n * 這里仍然為詳細(xì)注釋. */

• 下面對幾種注釋類型進(jìn)行描述。

文件頭注釋

• 一般@file后為空，Doxygen會默認(rèn)為是@file所在文件的文件名。[]表示可選，{}表示重復(fù)0到N次，<>表示必須參數(shù)，@author表示作者，@data表示日期，@version表示版本號。

/** * @file [file-name] * @brief brief description for the file. * @author <list of authors> * {@author <list of authors>} * [@author <authors description>] * @date <date> * @version <version number> * * detailed description for the file. */

類注釋

• header-file是類聲明所在的頭文件名字，header-name是要顯示的鏈接文字，一般為頭文件的真實(shí)路徑。

/** * @class <class-name> [header-file] [header-name] * @brief brief description for the class. * * detailed description for the class. */

函數(shù)注釋

/** * @brief brief description. * {@param <parameter-name> <parameter description>} * @exception <exception-object> <exception description> * {@exception <exception-object> <exception description>} * @return <description of the return value> * {@return <description of the return value>} * @note <text> * @remarks <remark text> * {@remarks <remark text>} * [@deprecated <description>] * [@since when(time or version)] * [@see references{,references}] */

@param	參數(shù)名及其解釋（param后加[in]表示輸入?yún)?shù)，param后加[out]表示輸出參數(shù)）
@exception	用來說明異常類及拋出條件
@return??	對函數(shù)返回值做解釋
@note??	表示注解，暴露給源碼閱讀者的文檔
@remark?	表示評論，暴露給客戶程序員的文檔
@since	表示從那個(gè)版本起開始有了這個(gè)函數(shù)
@deprecated	引起不推薦使用的警告
@see?	表示交叉參考

?成員注釋

• /**<用來注釋成員，放在成員后面，格式如下：

int var; /**< Detailed description after the member */

• 此語法對成員函數(shù)也適用。對于枚舉類型也可采用這種注釋，如下：

/** @brief Another enum, with inline docs */ enum AnotherEnum {V1, /**< value 1 */V2 /**< value 2 */ };

項(xiàng)目符號標(biāo)記注釋

/** * A list of events: * - mouse events * -# mouse move event * -# mouse click event\n */ 結(jié)果為：A list of events:。mouse eventsmouse move eventmouse click event

分組注釋

• 對于某幾個(gè)功能類似的代碼項(xiàng)（比如類、函數(shù)、變量）等，如果希望一起添加注釋，而又不想提升到模塊的概念，可以通過下面的方式：

/** * @name 組名 組的說明文字 * @brief 組的簡要注釋. * * 組的詳細(xì)注釋. * @{ */

• 組內(nèi)的代碼;
• 在一頁內(nèi)分組顯示。其中組名組名的命名符合c++命名規(guī)范。

/** @} */ //組結(jié)尾

?模塊注釋

• 進(jìn)行設(shè)計(jì)時(shí)，通常有模塊的概念，一個(gè)模塊可能有多個(gè)類或者函數(shù)組成，完成某個(gè)特定功能的代碼的集合。生成的模塊的注釋會單獨(dú)放在一個(gè)模塊的頁面中。使用下面的格式定義一個(gè)模塊：

/** * @defgroup 模塊名 模塊的說明文字 * @brief模塊的簡要注釋. * * 模塊的詳細(xì)注釋. * @{ */

代碼;

/** @} */ // 模塊結(jié)尾

• 其中模塊名Module-Name的命名符合c++命名規(guī)范。
• 任何其他代碼項(xiàng)（比如類、函數(shù)、甚至文件）如果要加入到某個(gè)模塊，使用ingroup命令即可。模塊之間使用ingroup命令，可以組成樹狀關(guān)系。例如要把文件util.cpp加入到模塊module_A中，格式如下：

/** * @file util.cpp * @ingroup module_A * @brief brief description of the module. * * detailed description of the module. * @ */

• 同樣，對于類和命名空間都可以加入到某模塊中，所不同的是把@file util.cpp換成對應(yīng)的@class class-name和@namespace namespace-name。
• 把多個(gè)代碼項(xiàng)一起添加到某個(gè)模塊中可以使用addtogroup命令，格式和defgroup類似，如下：

/** * @addtogroup模塊名 * @{ */

?

?

?

總結(jié)

以上是生活随笔為你收集整理的C++代码注释详解的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。