目錄

1、什么是Doxygen?.?3

2、撰寫正確格式的批注...?4

2.1常用指令介紹...?4

2.2簡述與詳述的方式...?6

2.3文件頭注釋...?6

2.4版權注釋...?6

2.5模塊定義（單獨顯示一頁）...?7

2.6分組定義（在一頁內分組顯示）...?8

2.7變量、宏定義、類型定義簡要說明...?8

2.8函數說明...?9

2.9枚舉類型定義...?9

2.10項目符號標記...?10

3、使用DoxyWizard生成CHM文檔...?11

?

?

?

1、什么是Doxygen?

Doxygen是一個程序的文件產生工具，可將程序中的特定批注轉換成為說明文件。通常我們在寫程序時，或多或少都會寫上批注，但是對于其它人而言，要直接探索程序里的批注，與打撈鐵達尼號同樣的辛苦。大部分有用的批注都是屬于針對函式，類別等等的說明。所以，如果能依據程序本身的結構，將批注經過處理重新整理成為一個純粹的參考手冊，對于后面利用您的程序代碼的人而言將會減少許多的負擔。不過，反過來說，整理文件的工作對于您來說，就是沉重的負擔。

Doxygen就是在您寫批注時，稍微按照一些它所制訂的規則。接著，他就可以幫您產生出漂亮的文檔了。

因此，Doxygen的使用可分為兩大部分。首先是特定格式的批注撰寫，第二便是利用Doxygen的工具來產生文檔。

目前Doxygen可處理的程序語言包含：

• C/C++
• Java
• IDL (Corba, Microsoft及KDE-DCOP類型)??

而可產生出來的文檔格式有：

• HTML
• XML
• LaTeX
• RTF
• Unix Man Page

而其中還可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透過一些工具產生出PS或是PDF文檔。

2、撰寫正確格式的批注

若需要通過Doxygen生成漂亮的文檔，一般有如下幾個地方需要使用Doxygen支持的風格進行注釋：
??? 1） 文件頭（包括.h和.cpp）
????????主要用于聲明版權，描述本文件實現的功能，以及文件版本信息等
??? 2） 類的定義
????????主要用于描述該類的功能，同時也可以包含使用方法或者注意事項的簡要描述
??? 3） 類的成員變量定義
????????在類的成員變量上方，對該成員變量進行簡要地描述
??? 4）?類的成員函數定義
???? ???在類定義的成員函數上方，對該成員函數功能進行簡要描述
??? 5） 函數的實現在函數的實現代碼處，詳細描述函數的功能、參數的含義、返回值的含義、使用本函數需要注意的問題、本函數使用其他類或函數的說明等

2.1常用指令介紹

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

?

@file	檔案的批注說明。 eg： @file??? stm32f10x_tim.c
@author	作者的信息 eg： @author? MCD Application Team
@brief	用于class或function的批注中，后面為class或function的簡易說明。 eg： @brief?? This file provides all the TIM firmware functions.
@param	主要用于函數說明中，后面接參數的名字，然后再接關于該參數的說明 eg： @param? TIMx: where x can be? 1, 2, 3, 4, 5 or 8 to select the TIM peripheral.
@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?本函數執行可能會產生超出范圍的異常
@todo	對將要做的事情進行注釋
@see	一段包含其他部分引用的注釋，中間包含對其他代碼項的名稱，自動產生對其的引用鏈接。
@relates	通常用做把非成員函數的注釋文檔包含在類的說明文檔中。
@since	通常用來說明從什么版本、時間寫此部分代碼
@deprecated
@pre	用來說明代碼項的前提條件
@post	用來說明代碼項之后的使用條件。
@code	在注釋中開始說明一段代碼，直到@endcode命令
@endcode	注釋中代碼段的結束。

?

2.2簡述與詳述的方式

在每個代碼項中都可以有兩類描述,?這兩類描述將在文檔中格式化在一起:?一種就是brief描述,?另一種就是detailed。?兩種都是可選的，但不能同時沒有。

顧名思義,?簡述(brief)就是在一行內簡述地描述。而詳細描述(detailed description)則提供更長,?更詳細的文檔。

一般注釋的描述由簡述開始，經過特殊分隔方式后，后面緊跟詳述的內容，javaDoc風格可以使用的分隔方法有以下兩種：

1）???????使用@brief?參數標識，空行作為簡述和詳述的間隔標識

1.???/**? ?@brief??Brief?description.??

2.????*????description?continued.??

3.????*??

4.????*????Detailed?description?starts?here.??

5.????*/?

2）?直接使用javaDoc風格，javaDoc風格自動以簡述開頭，以空行（或者小數點加空格）作為簡述與詳述的分割

1.???/**???Brief?description??

2.????*????description?continued?.?(注意:這里有一個小數點,加上一個空格)??

3.????*????Detailed?description?starts?here.??

4.????*/?

2.3文件頭注釋

2.4版權注釋

1.???/**

2.?????******************************************************************************

3.?????* @file??? stm32f10x_dma.c

4.?????* @author? MCD Application Team

5.?????* @version V3.5.0

6.?????* @date??? 11-March-2011

7.?????* @brief?? This file provides all the DMA firmware functions.

8.?????******************************************************************************

9.?????* @attention

10.????*

11.????* THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS

12.????* WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE

13.????* TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY

14.????* DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING

15.????* FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE

16.????* CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.

17.????*

18.????* <h2><center>&copy;?COPYRIGHT 2014??深圳電應普科技有限公司??</center></h2>

19.????******************************************************************************

20.????*/}

?

2.5模塊定義（單獨顯示一頁）?

在文檔注釋塊中使用'@defgroup'命令來定義一個組。命令有兩個參數，第一個參數用來唯一標識組，第二個參數是指明該組在文檔中顯示的標題。

1.???/**? ? ?

2.????*????@defgroup?模塊名?模塊的說明文字?

3.????* ??? @{

4.????*/?

5.????

...?定義的內容?...

7.????

8.???/**

9.????* ?????@}//?模塊結尾

10.???*/

?

如果你使用同一個組名一次以上那么你會遇到一個錯誤。你可以使用'\addtogroup'來代替'\defgroup'來防止doxygen只限制唯一的標識。它的用法和'\defgroup'是一樣的，不同的只是當多次使用一個組名的時候，它會自動將其中的內容和之前的組名合并。組的題目在這里是可選的，語法如下,

1.???/**? ? ?

2.????*????addtogroup <label>?

3.????* ??? @{

4.????*/?

5.????

...?定義的內容?...

7.????

8.???/**

9.????*????? @}

10.???*/

?

2.6分組定義（在一頁內分組顯示）

1.???/**? ? ?

2.????*????@name?分組說明文字?

3.????* ??? @{

4.????*/?

5.????

6.??...?定義的內容?...

7.????

8.???/**

9.????*????? @}//?模塊結尾

10.???*/

?

2.7變量、宏定義、類型定義簡要說明

由于Doxygen?對于批注是視為在解釋后面的程序代碼。也就是說，任何一個批注都是在說明其后的程序代碼。如果要批注前面的程式碼則需用下面格式的批注符號。

/*!<?成員變量描述?*/

1）在成員變量上面加注釋的格式

1.???/**?成員變量描述?*/?

2.???int??m_Var;?

2）在成員變量后面加注釋的格式

1.??int??m_color;?????/*!<?顏色變量?*/?????

?

1.???/** @brief?簡要說明文字（在前面加?@brief?是標準格式）?*/

2.??#define MIN_UINT 0???

?

1.???/*

2.????* ?分行的簡要說明?\n

3.????*??這是第二行的簡要說明

4.????*/

5.??int?b;??

?

2.8函數說明

1.???/*

2.????*?簡要的函數說明文字

3.????*? @param [in] param1?參數1說明

4.????*? @param [out] param2?參數2說明

5.????*? @return?返回值說明

6.????*/

7.???int func(int param1, int param2);

?

1.???/*

2.????*?打開文件?\n

3.????*??文件打開成功后，必須使用?::CloseFile?函數關閉。

4.????*? @param[in] file_name?文件名字符串

5.????*? @param[in] file_mode?文件打開模式字符串，可以由以下幾個模塊組合而成：

6.????*? - r?讀取

7.????*? - w?可寫

8.????*? - a?添加

9.????*? - t?文本模式(不能與?b?聯用)

10.???*? - b?二進制模式(不能與?t?聯用)

11.???*? @return?返回文件編號

12.???*? - -1?表示打開文件失敗

13.???

14.???*? @note?文件打開成功后，必須使用?::CloseFile?函數關閉

15.???*? @par?示例:

16.???*? @code

17.??????//?用文本只讀方式打開文件

18.??????int f = OpenFile("d:\\test.txt", "rt");

19.???*? @endcode

20.???

21.???*? @see ::ReadFile ::WriteFile ::CloseFile

22.???*? @deprecated?由于特殊的原因，這個函數可能會在將來的版本中取消。

23.???*/

24.??int OpenFile(const char* file_name, const char* file_mode);?

2.9枚舉類型定義

1.???/**?枚舉常量?*/

2.???typedef enum TDayOfWeek

3.???{

4.?????SUN = 0, /*!<??星期天（注意，要以?“<”?小于號開頭）?*/

5.?????MON = 1, /*!<??星期一?*/

6.?????TUE = 2, /*!<??星期二?*/

7.?????WED = 3, /*!<??星期三?*/

8.?????THU = 4, /*!<??星期四?*/

9.?????FRI = 5, /*!<??星期五?*/

10.????SAT = 6? /*!<??星期六?*/

11.??}

12.??/**?定義類型?TEnumDayOfWeek */

13.??TDayOfWeek TEnumDayOfWeek;

?

2.10項目符號標記

通過在每行的開頭添加一系列列對齊的減號('-')，可以生成一個列表。列表項也可以具有標號，這需要在減號的后面跟上一個'#'。列表也可以是嵌套的，這取決于列表項的縮進方式。注意不要忘記'-#'后面的空格。

?

1.?????/*!

2.??????*? A list of events:

3.??????*??? - mouse events

4.??????*???????? -# mouse move event

5.??????*???????? -# mouse click event\n

6.??????*??????????? More info about the click event.

7.??????*???????? -# mouse double click event

8.??????*??? - keyboard events

9.??????*???????? 1. key down event

10.?????*???????? 2. key up event

11.?????*

12.?????*? More text here.

13.?????*/?

The result will be:

A list of events:

• mouse events
• mouse move event
• mouse click event
  More info about the click event.
• mouse double click event
• keyboard events
• key down event
• key up event

3、使用DoxyWizard生成CHM文檔

安裝好后，開始菜單會多出doxygen菜單，打開里面的DoxyWizard。界面如下圖。

Step1是Doxygen的工作目錄，請指定一個已存在的非中文的文件夾。

Step2做具體配置工作。

首先是Wizard選項卡：

• Project

Project name:?項目名稱

Project version or id:?項目版本號

Source code directory:?項目源碼目錄

Destination directory:?文檔輸出目錄

?

• Mode

保持默認選項（Document Entity Only與Optimize for C++ output）即可。

?

• Output

要生成CHM文檔請選擇HTML項中的prepare for compressed HTML (.chm)。

同時將With search function (requires PHP enabled web server)的鉤去掉。

LaTeX，如果不需要在文檔中生成LaTeX公式的話可以不選。

?

• Diagrams

選擇第二項Use Build-In class diagram generator，將使用Doxygen內置的生成功能生成每個類的類圖（如果它只有一個類的時候是不會生成的?= =）。

如果需要使用更強大的功能比如類繼承體系圖，請選擇第三項Use dot tool from the GraphViz package，此功能需要安裝GraphViz軟件。

?

其次是Export選項卡，配置項比Wizard內容多出許多，這里只做簡單介紹。

• Project

OUTPUT_LANGUAGE，選擇Chinese。

TAB_SIZE?是Tab的長度，默認為8，大家根據自己喜好……

?

• Build

默認是會生成public方法，但是貌似有時會莫名奇妙地少掉一些方法的詳細信息。

這里也選上EXTRACT_ALL，它保證輸出所有public方法及protected方法，static方法不在此范圍內。

若要包含static方法的注釋，請選中EXTRACT_STATIC。

同理EXTRACT_PRIVATE。

我們生成文檔的目的是為了方便各位調用類與函數，因此生成ALL、STATIC、LOCAL_CLASSES就好了吧?= =。

?

• Messages

生成時的提示信息，默認即可。

?

• Input

Input為輸入目錄，支持多個目錄，我們可以放入項目目錄和Include目錄。

下面的Exclude是忽略目錄與文件。

?

• Source Browser

源碼瀏覽器，默認即可。

?

• Index

鉤選ALPHABETICAL_INDEX，類中將有一個組合類型索引項。如下圖所示：

?

• HTML

如果你之前選擇了prepare for compressed HTML (.chm)，

這里的GENERATE_HTMLHELP項會是鉤選狀態。

它下面的CHM_FILE填寫你的CHM文檔名字。

HHC_LOCATION則選擇你的HTML Help WorkShop安裝目錄下的hhc程序，

一般會在C:/Program Files/HTML Help Workshop/hhc.exe。

Doxygen生成的默認是UTF-8，因此若不指定CHM_INDEX_ENCODING為GBK的話，CHM會有部分亂碼。

鉤選TOC_EXPAND，doxygen會為你生成左邊樹目錄。

?

• Dot

如果你選用內置的生成功能（即選擇Use Build-In class diagram generator），此時CLASS_DIAGRAMS會是鉤選狀態，而HAVE_DOT則是未選狀態，默認即可;

如果你選用GraphViz的dot工具生成（即選擇Use dot tool from the GraphViz package）情況則相反，請你鉤選上CLASS_DIAGRAMS。此時你需要設置下面的DOT_PATH為GraphViz的安裝目錄，否則將無法生成。

另外以下選項鉤選則生成對應的圖，不選則不生成：

• CLASS_GRAPHS?????????????????????????類圖
• COLLABORATION_GRAPH ?????協作圖
• GROUP_GRAPHS ??????????????????????組圖
• UML_LOOK??????????????????????????????????是否UML外觀
• INCLUDE_GRAPH?????????????????????? include
• INCLUDED_BY_GRAPH????????????被include
• CALL_GRAPH???????????????????????????????調用
• CALLER_GRAPH??????????????????????????被調用
• DIRECTORY_GRAPH???????????????????????????目錄圖
• GRAPHICAL_HIERARCHY??????????????????繼承體系圖

建議鉤選以上下劃線的幾項。效果應如下所示：

DOT_IMAGE_FORMAT是生成的圖片類型，有PNG/JPG/GIF三種格式可選。

?

其他項沒有用過，請大家自己研究?= =。

?

配置好后即可運行，進入Run選項卡，單擊Run doxygen即開始生成。

對話框會顯示調試信息，生成好后點擊下面的Show HTML Output可以打開生成的HTML首頁。

chm文件則在你指定的生成目錄中自己找。

?

關閉前不要忘了保存配置文件，下次可以繼續使用。

它會自動提示你是否需要保存，你也可以選擇File菜單的Save項自己保存。

總結

以上是生活随笔為你收集整理的C语言编程规范--代码注释的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。