常用注釋語法

• 注釋寫在對應的函數或變量前面。JavaDoc類型的多行注釋風格如下：

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

• 一般注釋中有簡要注釋和詳細注釋，簡要注釋有多種標識方式，這里推薦使用@brief命令強制說明，例如：

/** * @brief 這里為簡要注釋. * * 這里為詳細注釋. */

• @brief之后為簡要注釋，簡要注釋結束的標志是一個點號，或一個空行。簡要注釋之后的注釋為詳細注釋，因此也可以寫成：其中\n為換行符。

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

• 下面對幾種注釋類型進行描述。

文件頭注釋

• 一般@file后為空，Doxygen會默認為是@file所在文件的文件名。[]表示可選，{}表示重復0到N次，<>表示必須參數，@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是要顯示的鏈接文字，一般為頭文件的真實路徑。

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

函數注釋

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

?成員注釋

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

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

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

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

項目符號標記注釋

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

分組注釋

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

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

• 組內的代碼;
• 在一頁內分組顯示。其中組名組名的命名符合c++命名規范。

/** @} */ //組結尾

?模塊注釋

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

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

代碼;

/** @} */ // 模塊結尾

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

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

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

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

?

?

?

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。