1. 程式人生 > >Doxygen 常用指令以及C++註釋風格

Doxygen 常用指令以及C++註釋風格

        在註釋中加一些Doxygen支援的指令,主要作用是控制輸出文件的排版格式,使用這些指令時需要在前面加上“\”或者“@”(JavaDoc風格)符號,告訴Doxygen這些是一些特殊的指令,通過加入這些指令以及配備相應的文字,可以生成更加豐富的文件,下面對比較常用的指令做一下簡單介紹。

@file

檔案的批註說明。

@author

作者的資訊

@brief

用於class 或function的簡易說明

eg:

@brief 本函式負責列印錯誤資訊串

@param

主要用於函式說明中,後面接引數的名字,然後再接關於該引數的說明

@return

描述該函式的返回值情況

eg:

@return 本函式返回執行結果,若成功則返回TRUE,否則返回FLASE

@retval

描述返回值型別

eg:

@retval NULL 空字串。
@retval !NULL 非空字串。

@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的說明
    };