linux c/c++ 代码使用 doxygen 自动生成文档
www.doxygen.org 的使用非常方便，下面分成2步介紹一下
1. 注釋風格，需要在c/c++代碼中按照下面的風格添加注釋，基本上還是很順手的
C++的注釋風格 主要使用下面這種樣式：即在注釋塊開始使用三個反斜杠‘/’
文件注釋
/**
*@file 文件名
*@brief 概述
*
*詳細概述
*
*@author 作者,包含email等
*@version 版本號(maj.min，主版本.分版本格式)
*@date 日期
*/
?
命名空間的注釋
///@brief 簡單概述
///
///詳細概述
?
類定義注釋
對需要的類增加注釋，需要 說明類的設計方法，類的使用指南，說明類的不變項
?
///@brief 簡要概述
///
///詳細說明
///
///使用指南設計函數調用可以@ref 函數名 用于引用其他的說明
///
///其他說明，重寫父類函數加以特殊實現
///
///@invariant 類不變項，例如哪些值不會超多少多少
///
class xxx
{…
數據聲明注釋
行尾說明
Type varName;///< 說明
?
多行說明
///說明
///
///
Type varName;
函數注釋規范
///@brief 簡單概述
///
///詳細說明
///@param[in|out] 參數名，in，out表示輸入還是輸出
///@pre 前者條件
///@return 說明
///@retval 返回值 說明, 這個是可選的
///@post 說明函數完成后的世界狀態
代碼標記數值規范
///@todo 將要做的代碼
///@bug 表示此處的bug描述
?
枚舉變量的注釋示例?
///????顏色的枚舉定義 ?
///? ?
///????該枚舉定義了系統中需要用到的顏色\n ?
///????可以使用該枚舉作為系統中顏色的標識 ?
enum?TEnum? ?
{? ?
????RED,????????????///<?枚舉，標識紅色????? ?
????BLUE,???????????///<?枚舉，標志藍色????? ?
????YELLOW??????????///<?枚舉，標志黃色.????? ?
}enumVar; ? ??
附：Doxygen支持的指令
概述
可以在注釋中加一些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 本函數 執行可能會產生超出范圍的異常 |
==================
2 ?linux下使用doxygen
我的開發環境是ubuntu， 默認有doxygen 命令，如果沒有可以從官網下載一個編譯安裝之
doxygen工具的使用簡單的2步就夠了：
2.1 生成默認配置文檔
doxygen -s -g yourconfigname
這一條命令就可以生成一個叫 “yourconfigname” 的配置文檔
接下來需要打開這個文檔，對其中某些字段做配置，一般來說，只需要配置其中十幾個字段就可以：
#?項目名稱，將作為于所生成的程序文檔首頁標題
PROJECT_NAME?? ? ? ? ? ?= “Test“
#?文檔版本號，可對應于項目版本號，譬如?svn?、?cvs?所生成的項目版本號
PROJECT_NUMBER?? ? ? ?= "1.0.0”
#?程序文檔輸出目錄
OUTPUT_DIRECTORY?? ? =? doc/
#?程序文檔語言環境
OUTPUT_LANGUAGE?? ? = Chinese
#?如果是制作?C?程序文檔，該選項必須設為?YES?，否則默認生成?C++?文檔格式
OPTIMIZE_OUTPUT_FOR_C?? = YES
#?對于使用?typedef?定義的結構體、枚舉、聯合等數據類型，只按照?typedef?定義的類型名進行文檔化
TYPEDEF_HIDES_STRUCT?? ?= YES
#?在?C++?程序文檔中，該值可以設置為?NO?，而在?C?程序文檔中，由于?C?語言沒有所謂的域?/?名字空間這樣的概念，所以此處設置為?YES
HIDE_SCOPE_NAMES? ? ? ? = YES
#?讓?doxygen?靜悄悄地為你生成文檔，只有出現警告或錯誤時，才在終端輸出提示信息
QUIET? ?= YES
#?只對頭文件中的文檔化信息生成程序文檔
FILE_PATTERNS? ? ? ? ? = *.h
#?遞歸遍歷當前目錄的子目錄，尋找被文檔化的程序源文件
RECURSIVE?? ? ? ? ? ? ? = YES
#?示例程序目錄
EXAMPLE_PATH? ? ? ? ? ?= example/
#?示例程序的頭文檔?(.h?文件?)?與實現文檔?(.c?文件?)?都作為程序文檔化對象
EXAMPLE_PATTERNS? ? ? ?= *.c ?*.h
#?遞歸遍歷示例程序目錄的子目錄，尋找被文檔化的程序源文件
EXAMPLE_RECURSIVE? ? ? = YES
#?允許程序文檔中顯示本文檔化的函數相互調用關系?
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION? ? = YES
REFERENCES_LINK_SOURCE = YES
#?不生成?latex?格式的程序文檔
GENERATE_LATEX? ? ? ? ?= NO
#?在程序文檔中允許以圖例形式顯示函數調用關系，前提是你已經安裝了?graphviz?軟件包
HAVE_DOT? ? ? ? ? ? ? ?= YES
CALL_GRAPH? ? ? ? ? ? = YES
CALLER_GRAPH? ? ? ? = YES
#?讓?doxygen?從配置文件所在的文件夾開始，遞歸地搜索所有的子目錄及源文件
RECURSIVE = YES???
#?在最后生成的文檔中，把所有的源代碼包含在其中
SOURCE BROWSER = YES
$?這會在?HTML?文檔中，添加一個側邊欄，并以樹狀結構顯示包、類、接口等的關系
GENERATE TREEVIEW?＝?ALL
2.2 執行命令
doxygen yourconfigname
這一條命令就可以在指定的目錄下生成 html 目錄（根據配置決定，也可以生成幫助文檔等）
2.3 用apache等存放剛剛生成的html目錄
比如我的機器安裝了apache,則可以在 /var/run/www 目錄下建一個軟連接
連接到剛剛生成好的 html 目錄，然后就可以從瀏覽器訪問文檔了，下面是我的項目的文檔界面
?
?
下面這個是win上面使用的例子：http://wildpointer.net/2012/04/14/doxygen_graphviz/
其他參考：
http://blog.csdn.net/blood008/article/details/6567169
轉載于:https://www.cnblogs.com/jiayy/p/doxygen.html
總結
以上是生活随笔為你收集整理的linux c/c++ 代码使用 doxygen 自动生成文档的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： C++(2013.11.27)
- 下一篇： linux下编译wpa_supplica