Doxygen 中文文檔

原文：http://doxygen.nl/manual

本文檔摘取重點進行了介紹。

Getting started

doxygen是解析源文件和生成文檔的主要程序。詳細使用方法可以參見Doxygen usage 。doxywizard是帶界面的程序，可以用界面編輯配置文件和運行doxygen。主要關系圖如下：

Step 0：是不是你想要的的。

默認支持的語言有：C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Fortran and D.

Step 1：創建配置文件

可以使用命令doxygen -g <config-file>基于模板生成配置文件。配置文件的格式類似于Makefile。詳細可以參見 Configuration 。可以試著用doxywizard來對配置文件進行編輯。

對于小的工程可以INPUT tag留空，會在當前目錄查找源文件。

對于大的工程，你可以將具體目錄設置給INPUT 。設置的時候可以使用FILE_PATTERNS （如，*.cpp *.h）。想要提柜遍歷， RECURSIVE需要設置成yes。可以使用 EXCLUDE and EXCLUDE_PATTERNS進行微調。如：

EXCLUDE_PATTERNS = */test/*

文件名后綴和對應的語言關系可以見：http://doxygen.nl/manual/starting.html

對于存在的沒有文檔的項目，可以將EXTRACT_ALL設置成YES，需要注意的是，之后沒有被文檔化的成員不會被再生成了。

SOURCE_BROWSER tag to YES啟用交叉引用。 INLINE_SOURCES to YES 將代碼包括到文檔中。

Step 2：運行doxygen

doxygen <config-file>

Step3: 源代碼文檔化格式

默認情況下EXTRACT_ALL 值為NO。doxygen只會為能夠識別的實體生成文檔信息。那么具體怎么做呢？對于namespace，class，members，有兩種方式：

在member，class，namespace聲明之前放置特殊的文檔化塊，對于file，class，namespace也可以放到聲明之后。詳細見：Special comment blocks ；

放到其他地方，同時放上結構化命令。參見： Documentation at other places

對于代碼而言通常采用第一種方式，對于其他文檔而言就只能采用第二種方式了。一些特殊的區塊可以被解析成html或latex。

在解析的時候會發生如下步驟：

• 對markdown格式進行解析；
• 執行相關的特殊命令；
• 星號空格去除（對應規則見原文）；
• 空行分段；
• 相關類創建超鏈接，如果以%開頭，則不會；
• Automatic link generation
• html和latex處理

doxygen-代碼文檔化

原文：http://doxygen.nl/manual/docblocks.html

這一章講兩個話題：

代碼中怎樣寫注釋，doxygen才會認得；

怎么組織，輸出結果看上去才更好看；

怎樣寫注釋

源代碼中的文檔注釋

此處針對類C的語言，其他的請看原文。

對于代碼中的每個實體，有兩種（或在某些情況下有三種）類型的描述，它們共同構成該實體的文檔；簡短描述和詳細描述都是可選的。對于方法和函數，還有第三種類型的描述，即所謂的in-body描述，它由方法或函數主體中找到的所有注釋塊的串聯組成。

通常情況下一個注釋塊中最多只有一個詳細描述和一個簡短描述，否則多個之間的順序是未定義的。（更多示例可以見原文）

/// /// brief brief description is start with %brief /// /// This is a detail description /// void test0() {} ? /// /// brief brief description is start with %brief /// /// This is a detail description /// void test1() {} ? /*** brief brief description** This is a detail description*/ void test2() {} ? /*!* brief brief description** This is a detail description*/ void test3() {} ? /*! brief brief description ?This is a detail description */ void test4() {} ? class Test { public:int value0; //!< member descriptionint value1; /*!< member description */int value2; ///< member descriptionint vluae3; // This is not be parsed };

其他位置的文檔注釋

上面的例子中是添加在定義的前面，但是對于有些情況，比如namespace，很多地方都會用到一個namespace，那么對應的文檔注釋應該添加在哪里比較合適呢？可能是針對這個問題，doxygen允許你將文檔注釋添加在任何地方。你可以將針對這種情況，將文檔注釋添加到約定的地方，方便查找即可。

這個時候需要用到結構化命令，結構化命令通常以或@開頭。如：

/*! class Testbrief A test class. ?A more detailed class description. */

這個文檔注釋是針對class Test添加的。其他的類似的結構化命令還有：

- struct - union - enum - fn 對函數進行文檔化注釋 - var - def - typedef - file - namespace - package 針對java packaeg - interface 針對IDL接口

更多內容參見：Special Commands

注意是：要文檔化注釋一些全局的對象，如函數等，需要在相同的文檔中，先文檔化注釋對應的file，如：

/// file test.h /// brief A document file /// /// Detail /// ? /// def MAX(a,b) /// brief brief /// /// Details

美化注釋塊

在寫注釋的時候，你可以使用pure文本，可以只用markdown格式，Markdown ，還支持一些 Markdown Extra。

還支持XML Commands ，以及html的子集subset 。

關于markdown的支持可以直接看原文：http://doxygen.nl/manual/markdown.html

doxygen - list

list示例如下：

/*! * A list of events:* - mouse events* -# mouse move event* -# mouse click eventn* More info about the click event.* -# mouse double click event** End of first list** - keyboard events* 1. key down event* 2. key up event** More text here.*/

顯示效果如下：

doxygen - grouping

在寫代碼的時候有時回了給代碼分組，會用到#pragma region Demo Functions，那么在使用doxygen的時候如何進行分組呢？這就是這一章要介紹的內容。

Modules

modules用來將things組合到一塊兒形成單獨的頁面。這個group的成員可以是文件，命名空間，類，函數，變量等。

使用defgroup 來定義一個group。該命令的第一個參數是group的ID，要求是唯一的，第二個參數是文檔中將會顯示出來的group的名字。也可以通過ingroup 將函數類等添加到已有的group中。，也可以使用@{和@}將需要添加到group的內容囊括起來。 使用addtogroup可以避免group label唯一的條件。如果沒有對應的group則會創建一個，如果有，則會加入到原有的group中。

/// addtogroup A /// @{ /// int bool InA; /// @} ? /*** ingroup A*/ extern int VarInA; ? /*** defgroup IntVariables Global integer variables* @{*/ ? /** an integer variable */ extern int IntegerVariable; ? /**@}*/ ? /*** defgroup Variables Global variables*/ /**@{*/ ? /** a variable in group A */ int VarInA; ? int IntegerVariable; ? /**@}*/ ?

會生成如下的Module：

Member group

對于成員的group示例如下：

/** @name Group2* Description of group 2. */ ///@{ /** Function 2 in group 2. Details. */ void Memgrp_Test::func2InGroup2() {} /** Function 1 in group 2. Details. */ void Memgrp_Test::func1InGroup2() {} ///@}

結果顯示如下：

subpaging

subpage

公式

公式支持latex格式編寫。如果僅需要生成html，那么只需要USE_MATHJAX 設置成YES，即可。如果需要導出成文檔，那么參見：http://doxygen.nl/manual/formulas.html。

公式可以分為兩種，一種為內聯，一種為區塊。

一、針對內聯公式可以使用f$作為分隔符，示例如下：

The distance between f$(x_1,y_1)f$ and f$(x_2,y_2)f$ is f$sqrt{(x_2-x_1)^2+(y_2-y_1)^2}f$.

The distance between

and

is

.

二、針對區塊顯示的公式，單行顯示

f[|I_2|=left| int_{0}^T psi(t) left{ u(a,t)-int_{gamma(t)}^a frac{dtheta}{k(theta,t)}int_{a}^theta c(xi)u_t(xi,t),dxiright} dtright|f]

得到：

三、針對區塊多行顯示的公式，

f{eqnarray*}{g &=& frac{Gm_2}{r^2} &=& frac{(6.673 times 10^{-11},mbox{m}^3,mbox{kg}^{-1},mbox{s}^{-2})(5.9736 times 10^{24},mbox{kg})}{(6371.01,mbox{km})^2} &=& 9.82066032,mbox{m/s}^2f}

得到：

顯示表格

可以使用markdown格式，以及html實現。詳細見：http://doxygen.nl/manual/tables.html。

圖

doxygen內建支持生成c++的類繼承關系圖。

doxygen可以使用graphviz的dot工具來生成更加高級的圖例。http://www.graphviz.org/。

如果你的路徑中能夠找到dot，你可以將HAVE_DOT設置成YES，讓doxygen使用它。

doxygen可以使用dot工具來生成下面的圖：

• 類層次結構。僅支持html。
• 類繼承關系；
• include依賴關系；
• 針對class和struct，會有和基類繼承關系；使用其他struct和classes的關系；
• 如果CALL_GRAPH或CALLER_GRAPH設置成YES，函數調用關系也會給出（見；callgraph，hidecallgraph

可以使用 layout file 來確定哪些圖例需要顯示。

可以使用DOT_GRAPH_MAX_NODES and MAX_DOT_GRAPH_DEPTH 對深度和節點數進行限制。

不是dot工具生成的圖例：

• 黃色的表示類；
• 白色表示當前頁面顯示的類；
• 灰色表示沒有文檔化的類；
• 實線深藍箭頭表示public繼承關系；
• 虛線深綠箭頭表示protected繼承關系；
• 點線深綠箭頭表示private繼承關系；

針對dot生成圖：

• 白色表示class或者struct或者file。
• 紅色邊框的box，表示還有很多箭頭沒有顯示出來，為了使得圖不至于太大，圖被截斷了；
• 黑色的框表示當前顯示的類；
• 深藍色箭頭表示include關系，或public繼承；
• 深綠色箭頭表示protected繼承；
• 深紅色箭頭表示private箭頭；
• 紫色點線箭頭表示“使用”關系；

如下圖所示：

預處理

源文件在被doxygen解析之前可以被doxygen內置的c-preprocessor進行預處理操作。

默認情況下，只會啟用部分preprocessing。對判斷語句進行求值（如，#if），處理宏定義，但不會執行宏展開。

#define VERSION 200 #define CONST_STRING const char *#if VERSION >= 200static CONST_STRING version = "2.xx"; #elsestatic CONST_STRING version = "1.xx"; #endif

上面的代碼會被處理成：

#define VERSION #define CONST_STRINGstatic CONST_STRING version = "2.xx";

你可以將ENABLE_PREPROCESSING設置成NO，使得preprocessing不起作用。這種情況下，doxygen會讀取兩個語句，如：

static CONST_STRING version = "2.xx";static CONST_STRING version = "1.xx";

如果你想要展開CONST_STRING宏，可以將MACRO_EXPANSION設置成YES。那么結果將會是：

#define VERSION #define CONST_STRINGstatic const char * version = "2.xx";

注意，此時doxygen將會展開所有的macro定義。 你也可以單單指定需要展開的宏，通過將EXPAND_ONLY_PREDEF設置成YES，并且定義PREDEFINED or EXPAND_AS_DEFINED tag。

preprocessor 有幫助的一個例子是，在處理 __declspec（Microsoft）或__attribute__（GNU）的時候，如果沒有預處理，那么doxygen會困惑__declspec好像是個函數。

extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);

通過下面的配置可以告訴doxygen，遇到__declspec到底怎么處理。

ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = __declspec(x)=

這樣子，doxygen在碰到__declspec的時候直接將它刪除。

更復雜的一個例子，假設你有一個名為IUnknown的抽象基類的以下代碼片段被混淆了：

/*! A reference to an IID */ #ifdef __cplusplus #define REFIID const IID & #else #define REFIID const IID * #endif/*! The IUnknown interface */ DECLARE_INTERFACE(IUnknown) {STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;STDMETHOD(ULONG,AddRef) (THIS) PURE;STDMETHOD(ULONG,Release) (THIS) PURE; };

沒有宏擴展，doxygen會感到困惑。這個時候可以定義如下配置文件：

ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = "DECLARE_INTERFACE(name)=class name" "STDMETHOD(result,name)=virtual result name" "PURE= = 0" THIS_= THIS= __cplusplus

那么預處理之后的結果是：

/*! A reference to an IID */ #define REFIID/*! The IUnknown interface */ class IUnknown {virtual HRESULT QueryInterface ( REFIID iid, void **ppv) = 0;virtual ULONG AddRef () = 0;virtual ULONG Release () = 0; };

在某些情況下，您可能希望用其他內容替換宏名或函數，而不會將結果暴露給進一步的宏替換。你可以使用:=待敵=.如：

#define QList QListT class QListT { };

可以使用如下的定義：

PREDEFINED = QListT:=QList

如果你并不確定預處理能否得到你想要的結果，你可以執行如下命令：

doxygen -d Preprocessor

這樣，當完成preprocessor之后，doxygen會將結果輸出到控制臺。如果 set QUIET = YES and WARNINGS = NO，那么將會看不到輸出結果。

輸出格式

見官網：http://doxygen.nl/manual/output.html

查找

關于查找這里介紹三點

• 客戶端的查找；
• 服務端的查找；
• 帶外部index的服務端的查找；

更多的內容可以參見：http://doxygen.nl/manual/searching.html

客戶端的查找

最簡單的使能查找的方法是使用內置的客戶端的搜索引擎。這個引擎是使用javascript和DHTML實現的，只能完全運行在客戶端瀏覽器上。因此不需要額外的工具。

只要確保SEARCHENGINE to YES。以及SERVER_BASED_SEARCH is set to NO.

附加的一個高級功能搜索的實時提示，在輸入端的時候，會提示想要檢索的內容。

這個方法也有不足的地方，就是只能用來檢索symble。并不支持全文檢索的功能。對于大型項目，檢索的性能會降低。

服務端的查找

如果你計劃將html文檔放到web服務器上。并且websever能夠處理php，那么你可以使用doxygen內建的服務端檢索引擎。

需要在配置文件中將 SEARCHENGINE and SERVER_BASED_SEARCH 設置成YES，將EXTERNAL_SEARCH 設置成NO。

相比較于客戶端的優點是支持全文檢索，并且能夠比較友好的支持中等大小的項目。

缺點是不支持本地化檢索，如，"file://" URL，同時不支持實時檢索內容的提示。

注意：以后的版本中，這一條可能會被下一條功能取代。

帶外部index的服務端的查找

從1.8.3 開始，增加了另一種服務器端檢索引擎，使用此選項，doxygen將生成可搜索的原始數據，并將其留給外部工具進行索引和搜索，這意味著您可以使用自己選擇的索引器和搜索引擎。為了使doxygen的使用更加簡單，它提供了一個基于Xapian開源搜索引擎庫的示例索引器（doxyindexer）和搜索引擎（doxysearch.cgi）。

想要開啟這個功能，需要將 SEARCHENGINE, SERVER_BASED_SEARCH and EXTERNAL_SEARCH 都設置成YES。

更加詳細的內容可以參見：External Indexing and Searching

優點是可以更好的支持大項目，也可以將兩個項目以及外部數據合并到一個searchindex。這種與搜索引擎的交互方式，是的對于本地文件也能夠很好的支持。搜索結果也能得到更好的上下文信息。

缺點是需要web服務器能夠運行CGI庫。

定制化輸出結果

doxygen提供了多個層次的定制化功能。下面從細微調整，布局調整，xml形式完全控制，三個方面介紹。

細微調整

整體顏色調整

可以使用如下選項：

• HTML_COLORSTYLE_HUE
• HTML_COLORSTYLE_SAT
• HTML_COLORSTYLE_GAMMA

分別更改顏色的色調、飽和度和gamma校正。

Doxywizard 提供了能夠實時預覽效果的功能。

導航欄

默認情況下doxygen提供的導航欄位于頁面的上方，是通過下面的設置得到的：

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = NO

可以將導航欄設置成邊邊欄，使用：

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES

甚至擁有兩種導航方式：

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = YES

如果已經使用了外部的index，可以將所以的index禁用（這個沒玩過）：

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = NO

動態內容

為了使得html輸出內容更加具有交互性，doxygen提供了一些選項，這些選項默認是被禁用的。

• 啟用HTML_DYNAMIC_SECTIONS ，doxygen生成的一些內容會被折疊，用戶按照需求可以將其展開；
• 啟用HAVE_DOT 和 INTERACTIVE_SVG并將DOT_IMAGE_FORMAT to設置成svg，doxygen可以生成SVG圖像，用戶可以進行縮放平移；

頁眉、頁腳和樣式表更改

你可以創建不同的樣式表來更改文字的顏色，邊界等html中的屬性。你可以自定義頁眉頁腳。

可以先執行下面的命令：

doxygen -w html header.html footer.html customdoxygen.css

這個會創建三個文件。接著可以對這三個文件進行編輯。然后在配置文件中設定：

• HTML_HEADER = header.html
• HTML_FOOTER = footer.html
• HTML_EXTRA_STYLESHEET = my_customdoxygen.css

改變頁面布局

有時候你想要的改變頁面布局，那么之前提到的內容就沒有什么幫助了。

為此，doxygen提供了layout文件，然后可以對這個文件進行編輯，doxygen將會使用這個文件控制內容的展示。layout文件是一個xml文件。

默認的布局文件可以通過下面的命令生成：

doxygen -l

布局文件的默認名字是：DoxygenLayout.xml。

接下來是在配置文件中定義布局文件：

LAYOUT_FILE = DoxygenLayout.xml

文件最上層的結構如下：

<doxygenlayout version="1.0"><navindex>...</navindex><class>...</class><namespace>...</namespace><file>...</file><group>...</group><directory>...</directory> </doxygenlayout>

navindex表示每個html頁面上方顯示的導航tab。同時可以用 GENERATE_TREEVIEW來控制導航快里面的內容。每個tab被xml中的tab元素表示。

你可以通過將visible屬性設置為no來隱藏tab。你也可以自定義title屬性，覆蓋默認的title。如果title是空的。doxygen會自動進行補全。

你可以通過移動xml中的tabs，來改變tab的順序。但是，不要改變type屬性。僅支持固定的types類型。

你可以使用user type來增加自定義tabs。下面是一個例子：

<navindex>...<tab type="user" url="http://www.google.com" title="Google"/>...</navindex>

這里url可以使相對URL。如果url以@ref開頭，那么可以指向文檔的實體，如類，函數等。加入你定義一個page的時候使用了@page標簽，那么可以將這個page添加到tab上，如下：

<navindex>...<tab type="user" url="@ref mypage" title="My Page"/>...</navindex>

你也可以將tab group到一起，如下：

<navindex>...<tab type="usergroup" title="My Group"><tab type="user" url="http://www.google.com" title="Google"/><tab type="user" url="@ref mypage" title="My Page"/></tab>...</navindex>

navindex后面的元素表示了doxygen生成的不同頁面：

• class元素，表示用于生成的classes，structs，unions，interfaces的布局設定；
• namespace，用于namespace；
• file
• group
• directory

上述頁面的元素都表示一個信息片段。一些片段可以出現在每個類型的page中，有些是用于特定的頁面。

可用于每個頁面的通用元素有：

• briefdescription：頁面的簡單描述；
• detaileddescription：頁面的詳細描述；
• authorsection：表示頁面的作者section（只用于man pages）。和author or authors 是不一樣的；
• memberdecl：表示一個頁面中member的快速瀏覽。
• memberdef：頁面中詳細的memberlist。

針對class頁面的屬性：

• includes：表示為了獲取類定義需要的頭文件；
• inheritancegraph：表示類的繼承關系；
• collaborationgraph：表示類的協作關系圖；
• allmemberslink： 表示指向類的所有成員列表的鏈接。；
• usedfiles：表示從中提取類文檔的文件列表。

針對file page的元素有：

• includes：表示文件中有的#include語句列表；
• includegraph：表示include依賴圖；
• includebygraph：表示文件被引用的關系圖；
• sourcelink：表示這個文件對源文件的link；

使用xml定制化輸出

見原文：http://doxygen.nl/manual/customize.html#xmlgenerator

自定義命令

doxygen提供了很多special commands, XML commands, and HTML commands. 用來提高注釋的結構化。如果你覺得這些定義還不夠用。那么可以使用自定義命令。

一般情況下是夠用來的，此處不展開了，詳細可以跳轉：http://doxygen.nl/manual/custcmd.html

常見問題

如何在HTML中獲取索引頁上的信息 ?

你應該使用mainpage，如下：

/*! mainpage My Personal Index Page** section intro_sec Introduction** This is the introduction.** section install_sec Installation** subsection step1 Step 1: Opening the box* * etc...*/

生成的效果如下：

為什么我的類/文件/命名空間中的部分或所有內容沒有被文檔化？

請做如下check：

你的class/file/namespace被文檔化了沒？如果沒有，需要確認下EXTRACT_ALL有沒有設置成YES；

member是不是私有的，如果是，那么想要私有成員文檔化，需要將 EXTRACT_PRIVATE 設置成YES；

類中是否有不以分號結尾的函數宏（例如MY_macro（））？如果是這樣的話，你必須指示doxygen的預處理器移除它。 這通常歸結為配置文件中的以下設置：
ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = MY_MACRO()=
可以參見上文預處理一節。

當我將EXTRACT_ALL 設置成NO的時候，所有的函數都不會被文檔化了？

為了記錄全局函數、變量、枚舉、typedef和定義，應該使用包含一個file（或@file）命令的注釋塊記錄這些命令所在的文件。

或者，可以使用ingroup命令將所有成員放在一個組（或模塊）中，然后使用包含defgroup命令的注釋塊記錄該組。

對于成員函數或作為命名空間一部分的函數，應記錄類或命名空間。

我的自定義擴展名的文件無法正確地解析

doxygen只會通過INPUT tag標注的文件進行解析，可以通過FILE_PATTERNS來匹配特定的后綴。 然后，通過排除列為EXCLUDE的文件或與排除模式設置的 EXCLUDE_PATTERNS.來減少文件列表。

在過去，doxygen將所有擴展名未知的文件解析為C文件，這可能會導致不希望的結果。自1.8.8版以來，doxygen要求您指定一個映射，該映射告訴特定的文件擴展名，要使用哪個解析器。擴展映射可以通過EXTENSION_MAPPING進行設置。如果沒有設置mapping，那么對應文件的內容會被忽略。

如何使doxygen忽略某些代碼片段？

最簡單的方式是可以在同一個文件中用cond 和endcond 將需要忽略的內容包括起來。

也可以借用preprocessor，如果：

#ifndef DOXYGEN_SHOULD_SKIP_THIS/* code that must be skipped by doxygen */#endif /* DOXYGEN_SHOULD_SKIP_THIS */

然后通過下面的定義，可以做到忽略代碼塊的功效。

PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

在配置文件中，只要ENABLE_PREPROCESSING設置為YES，doxygen就應該跳過所有塊。

如何更改類文檔中#include之后的內容?

大多數情況下可以使用STRIP_FROM_INC_PATH。來帶上用戶定義的路徑。

你也可以對類做如下注釋：

/*! class MyClassName include.h path/include.h** Docs for MyClassName*/

這樣會得到：

#include <path/includ.h>

在類MyClassName的文檔中，與包含MyClassName定義的實際頭文件的名稱無關。如果想要用引號代替方括號，則：

/*! class MyClassName myhdr.h "path/myhdr.h"** Docs for MyClassName*/

如何排除所有的test目錄？

EXCLUDE_PATTERNS = */test/*

Doxygen會在運行文本中的某個地方自動生成指向MyClass類的鏈接。我如何在某個地方防止這種情況發生？

在類名字前面加上%。比如: %MyClass。doxygen將溢出%，并保持word unlinked。

為什么STL類的依賴沒有在dot圖中顯示？

需要打開 BUILTIN_STL_SUPPORT設置。

總結

以上是生活随笔為你收集整理的source insight3.5显示中文_Doxygen 中文文档的全部內容，希望文章能夠幫你解決所遇到的問題。

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