doxygen的使用與C/C++註釋規範

1.   doxygen的安裝與參數配置
1.1.  安裝
$ sudo apt-get install doxygen
以下可以選擇安裝
$sudo apt-get install doxygen-doc doxygen-gui graphviztexpower dot2tex graphviz-doc texpower-examples
1.2.  生成配置文件
在 shell 提示上，輸入命令 doxygen -g。這個命令在當前目錄中生成一個可編輯的配置文件 Doxyfile。可以改變這個文件名，在這種情況下，應該調用 doxygen -g<user-specified file name>
1.3.  修改配置參數
l        <OUTPUT_DIRECTORY>：必須在這裏提供一個目錄名，例如 /home/user1/documentation，這個目錄是放置生成的文檔文件的位置。如果提供一個不存在的目錄名，doxygen 會以這個名稱創建具有適當用戶權限的目錄。
l        <INPUT>：這個標記創建一個以空格分隔的所有目錄的列表，這個列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件。例如，請考慮以下代碼片段：
INPUT = /home/user1/project/kernel /home/user1/project/memory
在這裏，doxygen 會從這兩個目錄讀取 C/C++ 源代碼。如果項目只有一個源代碼根目錄，其中有多個子目錄，那麼只需指定根目錄並把<RECURSIVE> 標記設置爲 Yes。
l        <FILE_PATTERNS>：在默認情況下，doxygen會搜索具有典型 C/C++ 擴展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果<FILE_PATTERNS> 標記沒有相關聯的值，doxygen就會這樣做。如果源代碼文件採用不同的命名約定，就應該相應地更新這個標記。例如，如果項目使用 .c86 作爲 C 文件擴展名，就應該在 <FILE_PATTERNS> 標記中添加這個擴展名。
l        <RECURSIVE>：如果源代碼層次結構是嵌套的，而且需要爲所有層次上的 C/C++ 文件生成文檔，就把這個標記設置爲 Yes。例如，請考慮源代碼根目錄層次結構 /home/user1/project/kernel，其中有/home/user1/project/kernel/vmm 和/home/user1/project/kernel/asm 等子目錄。如果這個標記設置爲 Yes，doxygen 就會遞歸地搜索整個層次結構並提取信息。
l        <EXTRACT_ALL>：這個標記告訴 doxygen，即使各個類或函數沒有文檔，也要提取信息。必須把這個標記設置爲 Yes。
l        <EXTRACT_PRIVATE>：把這個標記設置爲 Yes。否則，文檔不包含類的私有數據成員。
l        <EXTRACT_STATIC>：把這個標記設置爲 Yes。否則，文檔不包含文件的靜態成員（函數和變量）。
l        <SOURCE_BROWSER>：把這個標記設置爲 Yes，自動加入源碼。
 
 
2.   文件註釋
2.1.  示例
/**
 * @file apply.c
 * @author lishujie
 * @version 1.0
 * @date 2013-12-12
 * @brief this brief
 * @details this's details
 */
2.2.  說明
l        “@file”後的文件名需與當前文件名一致
 
3.   結構體註釋
3.1.  簡潔樣例
typedef struct Mac_Config                                                               ///  the brief structcomment
{
         charmacaddr[QCT_OTHER_MACADDR_64];            ///< The brief mement comment
         chardevicename[QCT_OTHER_DEVNAME_64];         ///< The brief mement comment
         intchecked;                                                                              ///< The brief mement comment
} Mac_list;
3.2.  詳細樣例
/**
 * this is details struct
 */
typedef struct DynamicConfigT                                              ///  The brief mementcomment
{
         int     nApplyId;                                                      ///< The brief mement comment
         int     nTime;                                                                 ///< The brief mement comment
         int     nReboot;                                                   ///< The brief mement comment
 
    /** this is details mement comment */
         char**  aValTable;                                                        ///< The brief mement comment
         LocalHndl   pfnHndl;                                              ///< The brief mement comment
} DynamicConfig;
3.3.  說明
l        “///”與註釋間留有2個空格
l        “///<”與註釋間留有1個空格
l        結構體成員的詳細註釋寫在該成員上面
l        結構體成員的詳細註釋與上一成員間留1個空行
l        推薦結構體使用typedef類型定義
l        推薦使用簡潔的結構體註釋
 
4.   枚舉註釋
4.1.  樣例
typedef enum _COLOR       ///  The brief enum comment
{
BLACK,                                     ///< The brief member comment
NAVY,                                  ///< The brief member comment
}COLOR;
4.2.  說明
l        與結構體的簡潔註釋相同
 
5.   宏註釋
5.1.  簡潔樣例
/// This macro is toolong, so comment here briefly!
#define HTTP_REQUEST_LEN_MAX    APPLY_BUF_SIZE_BIG
5.2.  詳細樣例
/**
 * The detail macro comment, may be multi-line.
 * @param a The brief parameter comment
 * @param b The brief parameter comment
 * @return The brief return value comment
 */
#define MAX(a, b) ((a) > (b))? (a) : (b)
5.3.  說明
l        儘量少寫宏函數，可以使用內聯函數代替
l        推薦使用簡潔的宏註釋
 
6.   函數註釋
6.1.  簡潔樣例
/// The brieffunction comment, may be multi-line.
static int apply_login();
6.2.  詳細樣例
/**
 * The detail function comment, may bemulti-line.
 * @param cur_id The brief parameter comment
 * @return The brief return value comment
 * @brief The brief function comment
 */
static int reboot_enable( intcur_id )
6.3.  說明
l        簡述以///+空格開頭或使用@brief ，詳述以/**開頭
l        無參無返回值的簡單函數使用簡潔註釋
l        頭文件有聲明的函數註釋在頭文件中；否則註釋在代碼文件中
 
7.   其它註釋
l        代碼中其餘註釋一律使用普通的單行註釋“//”和多行註釋“/*”“*/”。
 
8.   附錄
8.1.  註釋換行
Doxygen 會忽略你註釋中的換行符，將多行註釋連接成一個連續行並使用空格隔開。如
果你希望保留兩行註釋之間的換行，需要在該行末加入“/n”。
8.2.  常用命令
命令
生成字段名
說明
@attention
注意
 
@author
作者
 
@bug
缺陷
鏈接到所有缺陷彙總的缺陷列表
@brief
簡要註釋
 
@code
 
代碼塊開始，與“nendcode”成對使用
@details
詳細註釋
 
@date
日期
 
@endcode
 
代碼塊結束，與“ncode”成對使用
@file
< 文件名> 文件參考
用在文件註釋中
@param
參數
用在函數註釋中
@return
返回
用在函數註釋中
@todo
TODO
鏈接到所有TODO 彙總的TODO 列表
@version
版本
 
@warning
警告
 
8.3.  vim+Doxygen方便的寫註釋
8.3.1.   安裝
下載 doxygen的 vim 插件
   http://www.vim.org/scripts/script.php?script_id=987
將下載的插件安裝到$VIMRUNTIME/plugin目錄下
在VIM的配置文件中(windows下的_vimrc，linux下的vimrc或者~/.vimrc)爲doxygentoolkit這個插件配置一些全局變量：
let g:doxygenToolkit_authorName="your name"
let g:doxygenToolkit_briefTag_funcName="yes"
8.3.2.   常用命令
Dox
DoxAuthor
DoxLic
8.4.  給source insight添加doxygen註釋風格
請參考：http://blog.csdn.net/dayong419/article/details/7932467