Doxygen 常用指令以及C++註釋風格
阿新 • • 發佈:2018-12-19
在註釋中加一些Doxygen支援的指令,主要作用是控制輸出文件的排版格式,使用這些指令時需要在前面加上“\”或者“@”(JavaDoc風格)符號,告訴Doxygen這些是一些特殊的指令,通過加入這些指令以及配備相應的文字,可以生成更加豐富的文件,下面對比較常用的指令做一下簡單介紹。
@file |
檔案的批註說明。 |
@author |
作者的資訊 |
@brief |
用於class 或function的簡易說明 eg:
|
@param |
主要用於函式說明中,後面接引數的名字,然後再接關於該引數的說明 |
@return |
描述該函式的返回值情況 eg: @return 本函式返回執行結果,若成功則返回TRUE,否則返回FLASE |
@retval |
描述返回值型別 eg:
|
@note |
註解 |
@attention |
注意 |
@warning |
警告資訊 |
@enum |
引用了某個列舉,Doxygen會在該列舉處產生一個連結 eg: @enum CTest::MyEnum |
@var |
引用了某個變數,Doxygen會在該列舉處產生一個連結 eg: @var CTest::m_FileKey |
@class |
引用某個類, 格式:@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h" |
@exception |
可能產生的異常描述 eg: @exception 本函式執行可能會產生超出範圍的異常 |
下面介紹C++的標註寫法,c++不推薦c語言式的/* */風格註釋,這裡,除了檔案頭使用這種註釋外其餘到使用C++風格的註釋。
【檔案頭】
/*!
* \file Ctext.h
* \brief 概述
*
*詳細概述
*
* \author 作者名字
* \version 版本號(maj.min,主版本.分版本格式)
* \date 日期
*/
【名稱空間】
/// \brief 名稱空間的簡單概述
///
///名稱空間的詳細概述
namespace text
{
……
}
【類說明】
/// \brief Ctext的doxygen測試
///
/// 作doxygen測試用
class Ctext
{
}
【函式標註】
/// \brief 函式簡要說明-測試函式
/// \param n1 引數1
/// \param c2 引數2
/// \return 返回說明
bool text(int n1,Ctext c2);
/// \brief 函式簡要說明-測試函式
///
/// 函式詳細說明,這裡寫函式的詳細說明資訊,說明可以換行
/// ,如這裡所示,同時需要注意的是詳細說明和簡要說明之間必須空一行
/// ,詳細說明之前不需要任何識別符號
/// \param n1 引數1說明
/// \param c2 引數2說明
/// \return 返回說明
/// \see text
bool text2(int n1,Ctext c2);
【變數及列舉】
int m_a; ///< 成員變數1m_a說明
double m_b; ///< 成員變數2m_b說明
/// \brief 成員變數m_c簡要說明
///
/// 成員變數m_c的詳細說明,這裡可以對變數進行
///詳細的說明和描述,具體方法和函式的標註是一樣的
float m_c;
/// \brief xxx列舉變數的簡要說明
///
/// xxx列舉變數的詳細說明--列舉變數的詳細說明和函式的詳細說明
///的寫法是一致的。每個列舉變數下可以進行單獨說明
enum{
em_1,///< 列舉值1的說明
em_2,///< 列舉值2的說明
em_3 ///< 列舉值3的說明
};