利用Doxygen為C程序生成注釋文檔

一、Doxygen工具的安裝

利用Doxygen工具生成API幫助文檔需要下載安裝以下三個軟件：

(1)Doxygen：可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的

LATEX、RTF參考手冊。本文中所使用的版本為：Doxygen-1.8.18.

(2)Htmlhelp：該軟件可以幫助您建立 HTML 格式的 HELP 文件。用于創(chuàng)建.chm文件，可

以從微軟官方網(wǎng)站下載。

(3)Graphviz：是一個由AT&T實驗室啟動的開源工具包，用于繪制DOT語言腳本描述的圖

形，與Doxygen配合使用，用于提取函數(shù)之間，頭文件之間的調(diào)用關(guān)系本文

中所使用的版本為:graphviz-2.38。

二、Doxygen工具的配置

1.打開Doxygen軟件如下圖所示：進行工程設(shè)置

2.模式設(shè)置如下圖所示

3.設(shè)置輸出格式如下圖所示

4.設(shè)置函數(shù)調(diào)用配置如下圖所示

5.輸出文檔字符集配置

6.Build頁面，這個頁面比較關(guān)鍵：

(1)EXTRACT_ALL：輸出所有的函數(shù)，但是private和static函數(shù)不屬于其管制。

(2)EXTRACT_PRIVATE：輸出private函數(shù)。

(3)EXTRACT_STATIC：輸出static函數(shù)。

(4)SHOW_INCLUDE_FILES ：是否顯示包含文件，如果開啟，幫助中會專門生成一個頁面，

里面包含所有包含文件的列表。

(4)INLINE_INFO ：如果開啟，那么在幫助文檔中，inline函數(shù)前面會有一個inline修飾詞

來標明。

(5)SORT_MEMBER_DOCS ：如果開啟，那么在幫助文檔列表顯示的時候，函數(shù)名稱會排

序，否則按照解釋的順序顯示。

(6)GENERATE_TODOLIST ：是否生成TODOLIST頁面，如果開啟，那么包含在@todo注解

中的內(nèi)容將會單獨生成并顯示在一個頁面中，其他的GENERATE選項同。

(7)SHOW_USED_FILES ：是否在函數(shù)或類等的幫助中，最下面顯示函數(shù)或類的來源文件。

(8)SHOW_FILES ：是否顯示文件列表頁面，如果開啟，那么幫助中會存在一個一個文件列表索引頁面。

7.Input選項設(shè)置

對源文件的編碼進行設(shè)置，設(shè)置的編碼格式應(yīng)與源文件的編碼格式相同，如果源文件不是

UTF-8編碼需要對源文件進行轉(zhuǎn)換一下，否則生成的幫助文檔會出現(xiàn)中文亂碼現(xiàn)象。

8.Source Browser設(shè)置

9.chm配置

10.配置Grapviz

11.運行Doxygen

三、Doxygen注釋格式

1.文件注釋

文件注釋是源代碼文件進行注釋，包含源文件和頭文件，文件注釋位于文件的開頭。主要包含以下內(nèi)容：文件名(@file )作者(@author)版本(@version)日期(@date)和簡要說明(@brief)，還可以包含：詳細描述(@details)版權(quán)(@copyright)注意(@attention)等。

2.函數(shù)注釋

函數(shù)注釋是對本函數(shù)進行說明，位于函數(shù)定義上方。函數(shù)注釋主要包含以下內(nèi)容：簡要說明(@brief)參數(shù)說明(@param)函數(shù)返回值情況(@return)函數(shù)返回值類型(@retval)

3.宏定義類型的注釋

4.結(jié)構(gòu)體和枚舉類型定義

結(jié)構(gòu)體注釋

枚舉類型注釋

5.項目注釋

主要對本項目進行簡單描述，通常位于main.c主函數(shù)文件頭部。注釋為/**@mainpage? */。主要包含項目名稱、功能描述、項目詳細描述、用法描述和軟件更新記錄等。

四、Doxygen常用的注釋命令

1.@author???????作者信息

2.@brief????????簡要說明概要信息

3.@bug??????????被標記的代碼會在Bug列表中出現(xiàn)

4.@class????????對類進行標注

5.@data?????????日期

6.@file?????????文件名

7.@param????????主要用于函數(shù)說明，對參數(shù)進行說明

8.@return???????描述函數(shù)的返回值情況

9.@retval???????描述函數(shù)返回值類型

10.@note????????注解

11.@attention???注意

12.@name????????分組名

13.@warning?????警告信息

14.@enum????????引入了某個枚舉

15.@var?????????引入了某個變量

16.@exception???可能產(chǎn)生的異常描述

17.@todo????????對將要做的事情進行注釋

18.@see?????????一段包含其他部分引用的注釋，中間包含對其他代碼項的名稱，自動產(chǎn)生對其的引用鏈接

19.@relates?????通常用做把非成員函數(shù)的注釋文檔包含在類的說明文檔中

20.@since???????從哪個版本后開始有這個函數(shù)的

21.@code????????在注釋中開始說明一段代碼，直到@endcode結(jié)束

22.@endcode?????在注釋中代碼段的結(jié)束

23.@remarks?????備注

24.@pre?????????說明代碼項的前提條件

25.@post????????說明代碼項之后的使用條件

26.@deprecated??這個函數(shù)可能會在將來的版本中取消

27.@defgroup????模塊名

???@{???????????模塊開始

???@}???????????模塊結(jié)束

28.@version?????版本號

29.@par?????????開始一個段落

30.@detail??????詳細描述

總結(jié)

以上是生活随笔為你收集整理的c++ doxygen 注释规范_利用Doxygen给C程序生成注释文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。