Doxygen 配置詳解

原創 Mourinho 2020-02-23 12:09

轉自http://blog.csdn.net/skyremember/archive/2009/03/06/3964446.aspx

（翻譯）Doxygen 配置詳解（1）- -


使用Doxygen文檔開發工具時需要進行的配置：

可執行文件 doxygen 是原代碼分析和生成文檔的主要工具. 請看 Doxygen usage 章節來獲取更詳細的使用幫助. 
Doxytag可執行文件---僅僅是用來實現幫助程序員生成不需要看原代碼就能瞭解工程部署信息的doxygen文檔的參考文檔( 例如：那些使用doxygen生成的文檔).請看Doxytag usage 章節來獲得更多的使用幫助.



                                           圖：Doxygen information flow

Step 1: 創建一個配置文件

Doxygen使用一個配置文件來確定它所有的設置. 每個工程都應該有它自己的配置文件.
一個工程可以只有一個原文件, 也可以是工程中所有原文件的遞歸掃描得到的原文件的樹狀視圖。
爲了簡化doxygen生成配置文件的工作, doxygen 可以爲你提供一個模板化的配置文件. 
1. 爲了創建一個模板化的配置文件，只需要調用doxygen並從命令行中敲入-g: 

doxygen -g <config-file>

其中 <config-file>是某個模板化的配置文件的文件名. 如果你省略了文件名, doxygen會爲你生成一個默認的Doxyfile的配置文件. 如果<config-file>是一個已經存在的文件名, doxygen 在生成配置模板之前，將會生成一個 <config-file>. Bak備份文件。
2. 如果你使用 - (例如：減號) 作爲文件名doxygen將會把你從鍵盤輸入的文字當作配置文件名。
配置文件有着和Makefile相似的格式.主要是：包含了很多的"標誌"分配符格式 (tags): 
例如：
TAGNAME = VALUE or 
TAGNAME = VALUE1 VALUE2 ... 
在生成文檔模板時，你可以使用默認（即：保留大多數的TAGS）詳細信息請看 Configuration 這一章節來獲取更多的信息. 
如果你不想使用文本編輯工具來編寫配置文件,你應該看看 doxywizard 章節的描述, 它是一個可以用來創建/讀/寫doxygen 配置文檔的圖形化工具，同時它也可以在路徑中進行全路徑配置來使doxygen正常工作。
3. 對於一個有很少的原文件和頭文件組成的C/C++工程來說, 你可以保留 INPUT 標誌爲"空" ，那麼 doxygen 將會在當前路徑下搜索原文件. 
4. 如果你的工程很大，你應該把你的工程文件的"根目錄"放在INPUT標誌後面,需要添加到工程中的文件應該放到FILE_PATTERNS 標誌之後(例如： *.cpp *.h). 至少是匹配了1項的文件才能被doxygen程序讀入並分析(如果省略了這項設置，則會使用doxygen配置列表中的格式).
5.       如果想要遞歸對原文件樹進行分析必須設置RECURSIVE標誌爲 YES.
6.       想在doxygen中使用更多的自定義規則進行分析，必須使用EXCLUDE標誌和 EXCLUDE_PATTERNS標誌。
7.       想忽略所有的 test路徑下的文件，使用下面的形式: 
 EXCLUDE_PATTERNS = */test/*
8. 對於C/C++文件Doxygen通常直接進行分析。 如果文件有 .idl或 .odl 擴展名，則doxygen會把它視爲 IDL文件。
8. 有.java 擴展名的將被視爲Java文件.
9. 使用 .cs作爲擴展名的文件將會視爲C# 文件. 
10. 使用.php, .php4擴展名的文件和用.inc 或 .phtml 擴展名的文件將被視爲PHP 原文件. 
11. 如果你想用doxygen爲已經存在的工程生成文檔。你首先要想象一下你的工程文檔最終使用什麼樣的格式排版，爲了實現這樣的目標，你必須要設置EXTRACT_ALL 標誌爲YES. 然後，doxygen表現出來的是它知道了所有你的工程文件的配置目標。
注意：如果設置EXTRACT_ALL 標誌爲YES 。則：undocumented members 之類的警告將不會再產生。 
12.   使用doxygen來分析一個現存的源代碼的某個部分或全部文件可以更清晰的明白源代碼各個功能模塊的定義和要實現的功能以及它們之間的交叉參考。
13.   使用Doxygen 生成交叉參考必須設置SOURCE_BROWSER 標誌爲 YES。也可以直接通過設置INLINE_SOURCES 標誌爲 YES 來實現把工程的所有源代碼包含進文檔中。(這樣方便了代碼的通覽).

Step 2: Running doxygen

To generate the documentation you can now enter: 
doxygen <config-file>
Doxygen 將會在輸出路徑中創建html, rtf, latex和/或man 路徑。 路徑和路徑中的文件格式是對應的HTML, RTF, 和Unix-Man格式. 
默認的路徑是doxygen的安裝路徑。可以使用 OUTPUT_DIRECTORY, HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, 和MAN_OUTPUT標誌來自定義配置文檔的輸出路徑。如果輸出路徑不存在doxygen將會爲你創建一個輸出路徑。 
生成的 HTML 可以通過使用瀏覽器瀏覽位於html路徑下的 index.html 文件. 如果瀏覽器支持層疊樣式表 (CSS) 那就更棒了。
生成的 必須要先用 編譯器進行編譯(我使用 teTeX 0.9版本，其中包含了 3.14159). 爲了簡化編譯文檔的生成過程，doxygen在latex 路徑下提供了一個Makefile 。在命令行latex路徑下敲入 make將會生成一個refman.dvi文件。 (假設你有一個文件叫做make of course). 你可以通過使用xdvi命令來查看這個文件或者使用dvips把它轉換成一個後綴是.ps的文件 refman.ps。
想實現分成2頁的效果可以使用make ps_2on1命令。PostScript文件最終會被髮送到PostScript打印機輸出。如果你沒有PostScript打印機，你可以使用ghostscript 命令把PostScript文件格式轉換成你的打印機能夠識別的文件格式。如果你已經安裝了ghostscript 解釋程序，那麼可以把文件轉換成 PDF格式，這只需要敲入make pdf (或make pdf_2on1)。
想生成PDF文件，你要把 PDF_HYPERLINKS 標誌設置成YES。
產生的man頁面文件可以通過man程序來進行查看。但是，你必須確定man路徑有相應的環境變量設置 (一般在 MANPATH環境變量中)。注意：man頁面文件的格式有一些限制 ，所以有些信息(像：class圖，交叉參考，公式等)將會丟失掉。

Step 3: Documenting the sources

儘管源代碼編制文檔的被作爲第3步，但是，在某些新的工程中，這個是作爲第1步來做的。 這裏，我假設你已經有了一些想用doxygen來對其進行文檔化（描述API接口和作用）的源代碼。
如EXTRACT_ALL 選項被設置成NO（默認情況下是NO ）那麼doxygen只會爲已經文檔化的成員，文件，類和命名空間生成文檔。如果你的文檔屬於這種情況，該怎麼辦呢？對於成員，類和命名空間有2種基本的設置：
1.成員，類或命名空間的前面安排一個描述或定義的塊兒。對於文件，類和命名空間成員來說，doxygen 允許直接在成員後面安排文檔。你可以參考：
 Special documentation blocks 瞭解更多特殊塊兒的設置。
2. 想在任何地方部署特殊的文檔塊兒（任何的文件或任何的路徑）和在文檔塊中添加一個"結構化"的命令。"結構化"的命令用來設置一個可被編製成文檔的鏈接。 (e.g. a member, class, namespace or file)。請看：Documentation at other places 瞭解更多的結構化命令的使用方法。
文件只能使用上面2中的方法進行設置，因爲沒有辦法把一個文檔塊兒放到一個文件的前面。
當然，文件成員（函數，變量，類型定義，define）不需要顯示的使用"結構化"命令，只需要把特殊的文檔塊兒放到文件中的最前面或最後面就可以了。
文檔內部的文檔塊兒在輸出爲HTML格式或其他格式輸出文件之前進行doxygen的語法分析：
它其實是在進行下面的步驟前進行分析：
  • 文檔內部的特殊"結構化"命令被執行的時候。請看： Special Commands 章節獲取所有的命令參考信息。
  • 如果某行中使用"空格+後面使用1個或多個*號"，或者是很多的"空格"符，則所有的空格和"*"號都會被刪除。
  • 所有的"空行"都會被視爲"圖形分隔符"。這項安排可以使你有"部署自定義圖形分隔符"的能力，以產生更具可讀性的文檔。
  • Doxygen將會爲所有已經歸檔的classes生成鏈接。
  • 如果在文檔中找到符合doxygen文檔格式的成員，那麼也會爲members創建鏈接。請參考：Automatic link generation獲取更多的如何自動化文檔鏈接。

文檔中的HTML標誌被解釋和轉換成相應的輸出。請看：HTML Commands章節獲取更多的關於HTML標誌的使用信息。

 

（翻譯）Doxygen 配置詳解（2）- -

注意：可以任意轉載，但請註名出處

使用Doxygen文檔開發工具時需要進行的配置：

可執行文件 doxygen 是原代碼分析和生成文檔的主要工具. 請看 Doxygen usage 章節來獲取更詳細的使用幫助. 
Doxytag可執行文件---僅僅是用來實現幫助程序員生成不需要看原代碼就能瞭解工程部署信息的doxygen文檔的參考文檔( 例如：那些使用doxygen生成的文檔).請看Doxytag usage 章節來獲得更多的使用幫助.

Doxygen 使用說明

Doxygen 是一個基於命令行的實用工具。在命令行使用—help可以顯示關於各種命令的簡短描述。
所有的命令開關都包括前導字符-， 後面跟什麼命令（1個字符或是多個字符）取決於你的選擇。
爲了爲你的工程產生一個手冊，典型的情況----你需要經過下面幾個步驟：
1.      你想要在你的文檔中使用特殊的塊狀標識 (請參考Special documentation blocks章節)。
2.      可以通過使用doxygen 中的-g 來創建配置文件(請參考Configuration章節)：

doxygen -g <config_file>

3.      你需要針對你的工程編寫相應的配置文件。在配置文件中你可以指定輸入文件以及很多其它的信息。
4.      通過使用下面的命令來對你配置過的文件產生相應的文檔：

doxygen <config_file>

如果你使用老版本的doxygen生成過配置文件，你可以通過運行doxygen 中的 -u 命令來對其進行更新。

doxygen -u <config_file>

在原來配置文件中的所有信息都會被替換成新的配置文件。所有新版本doxygen中的配置都會使用默認值。但是，你改動前的原來的配置文件中的所有的註釋都會被自動刪除。 
如果你想讓產生的文檔能夠按照某種你自定義的格式進行顯示的話。如果你編輯了下面的內容doxygen 能夠幫你產生自定義的樣式，頭部顯示內容，腳註形式：

  • 默認的情況下，HTML中會產默認的頭部(請查看 HTML_HEADER獲得更詳細的信息)，默認的腳註 (請查看HTML_FOOTER獲得更詳細的信息)，默認的樣式(請查看HTML_STYLESHEET獲得更詳細的信息)，需要用到的命令如下：
·       doxygen -w html header.html footer.html stylesheet.css
  • 想要產生 LaTeX 形式的輸出格式，你可以創建refman.tex的第1部分 (請查看LATEX_HEADER獲得更詳細的信息)。同時，也可以在某個文件中加入下面的命令來豐富文檔最終的頭部顯示樣式：（下面是默認的2個文件）
·       doxygen -w latex header.tex doxygen.sty
  • 想要產生RTF形式的輸出格式, 你可以創建一個默認的樣式格式配置文件 (請查看RTF_STYLESHEET_FILE獲得更詳細的信息)：
·       doxygen -w rtf rtfstyle.cfg

注意:

  • 如果你不想對配置文件中的每一項都進行編制，你可以使用-s命令。通過與-u同時使用，可以實現在現存文檔中增加或排除已存在的配置文件。如果你想向我報告BUG，請使用-s命令。

想要使用doxygen從鍵盤讀/寫信息而不是從輸入/輸出文件讀寫信息，你需要使用-for命令（後面跟上你想指定的文件名）。

 

（翻譯）Doxygen 配置詳解（3）- -

注意：可以任意轉載，但請註名出處

使用Doxygen文檔開發工具時需要進行的配置：

可執行文件 doxygen 是原代碼分析和生成文檔的主要工具. 請看 Doxygen usage 章節來獲取更詳細的使用幫助. 
Doxytag可執行文件---僅僅是用來實現幫助程序員生成不需要看原代碼就能瞭解工程部署信息的doxygen文檔的參考文檔( 例如：那些使用doxygen生成的文檔).請看Doxytag usage 章節來獲得更多的使用幫助.

Doxytag 使用說明

Doxytag 是一個基於命令行的小程序。它能夠產生標誌文件。這些標誌文件能夠被doxygen使用作爲自己的標誌文件。這些標誌文件能夠被用來爲產生外部文檔產生參考信息。 (例如：那些要被doxygen使用到，但是被包含在輸入文件中的部分)。
一個標誌文件包含關於這個文件中的classes，成員的相關信息。Doxytag能夠直接從HTML文件中抽取這些信息。 這樣就有了一個好處，不需要源代碼就能夠從doxytag中知道源代碼到底有什麼文件組成，每個文件的組成和它們的功能，以及文件之間的相互關係。
通過在doxygen中進行的配置文件中進行相應的配置，你能夠很容易的在GENERATE_TAGFILE 之後放上相應的標誌文件名。 
關鍵: 
如果你使用標誌文件，通過doxygen生成links將會包含dummy（啞元）鏈接。你必須運行installdox腳本程序把這些dummy鏈接轉化成真實的鏈接。請參考Installdox usage 章節獲取更多的相關信息。Dummy鏈接看起來好象是沒什麼用處的，但實際上它非常的有用---如果你想要把外部文檔移動到任何位置的的時候你會發現它很有用。只要你運行着installdox，文檔不需要通過doxygen進行重新生成。
注意: 
因爲，通常要在HTML文檔中形成某種特定的結構，但是，通過doxygen生成的HTML文件中只有HTML或者是按照字母排序的classes視圖形式。Doxytag只能讀取HTML格式。 
Doxytag能夠爲一個在HTML目錄下的所有的HTML文件建立標誌。如果沒有沒有進行設置，Doxytag將從當前路徑讀取所有的擴展名爲html的文件。 如果使用 doxytag中的-t命令就能生成一個標誌文件。
例 1: 
假如下面列出的出現在examples目錄下的example.cpp文件，以特殊塊兒顯示的文件形式，沒有它的源文件。那麼你就很幸運了，可以通過軟件包中包含的分配器可以過doxygen生成包含HTML文檔的文檔形式顯示的文件。

/** A Test class.

*  More details about this class.

*/


class Test

{

  public:

    /** An example member function.

     *  More details about this function.

     */

    void example();

};

 

void Test::example() {}

 

/** /example example_test.cpp

* This is an example of how to use the Test class.

* More details about this example.

*/

你只用使用下面的命令從HTML文件創建一個標誌文件就能達到分析源文件由哪些部分組成，各個部分都是什麼功能，以及它們之間有什麼聯繫：

doxytag -t example.tag example/html

上面的examples是HTML文檔原始的路徑。這樣，你就能在你自己的代碼塊兒中使用上面的標誌文件了，如下所示照葫蘆畫瓢即可：

/*! A class that is inherited from the external class Test.

*/

 

class Tag : public Test

{

  public:

    /*! an overloaded member. */

    void example();

};

Doxygen能夠爲你的文檔提供包含上所有指定過的鏈接選項。因爲標誌文件不能確定文檔定位在哪裏，你必須通過運行installdox腳本程序確定doxygen生成的文件放置到什麼位置。(請參考 Installdox usage 章節獲得更多的信息)。
注意：（不管你移動別人的文檔或者是別人移動你的文檔）把外部的文檔移動到一個不同的路徑下面或者改變鏈接設置，你只需簡單的運行腳本就能實現所有連接的同步更新。 
點擊 here 查看通過doxygen生成的相應的HTML文檔和下面的第2個例子。 
例2: 
使用下面的命令行生成一個標記文檔：

doxytag -t qt.tag $QTDIR/doc/html

翻譯）Doxygen 配置詳解（4）- -

注意：可以任意轉載，但請註名出處

使用Doxygen文檔開發工具時需要進行的配置：

可執行文件 doxygen 是原代碼分析和生成文檔的主要工具. 請看 Doxygen usage 章節來獲取更詳細的使用幫助. 
Doxytag可執行文件---僅僅是用來實現幫助程序員生成不需要看原代碼就能瞭解工程部署信息的doxygen文檔的參考文檔( 例如：那些使用doxygen生成的文檔).請看Doxytag usage 章節來獲得更多的使用幫助. 

配置

格式

一個配置文件是一個和Makefile有着類似結構的ASCII 文本文件，默認的配置文件名是Doxyfile。它是經doxygen分析後生成的。這個配置文件以固定的格式包含標記和新行 。配置文件中的設置是"大小寫敏感"的。註釋可以放在文檔中的任何的位置(內部使用的"引號"除外)。註釋採用的是以"#"開始的 單行註釋形式。
文 件中包含了很多"賦值語句"的形式。每條語句主要包含了一個後面跟着一個"="號的標誌名TAG_NAME， 然後後面是1個或者多個值。如果相似的標誌已經被多次的使用，那麼最後使用的標誌將會覆蓋掉前面使用過的標誌。下面列出了所有命令的列表，表中的" +=" 號 可以用來代替"=新值"。如果使用多個命令參數，它們之間是"不能有空格符"出現的。如果某個命令參數需要使用"空格符"，則必須使用""把這個命令參數 括起來。寫成多行時，必須使用反斜槓 (/)做爲該行的結束。環境變量可以通過使用$(ENV_VARIABLE_NAME)進行擴展。 
想包含別的配置文件中的相關內容，只需使用下面格式的 @INCLUDE 標誌即可： 

@INCLUDE = config_file_name

被包含的文件通常先從當前路徑搜索。你也可以通過使用路徑指定自定義路徑中被包含的配置文件。使用命令 @INCLUDE_PATH ，後面跟上被包含的配置文件的具體的路徑，如下所示：

@INCLUDE_PATH = my_config_dir

配置選項可以被分成幾類。下面給出的命令開關（或者說：配置選項）以字母順序給出：

（翻譯）Doxygen 配置詳解（5）-----詞彙表- -

下面是需要涉及到的配置參數，通過對它們進行具體的設置能夠實現想要的自定義效果.......

有些地方翻譯的不太合適，請參照相關的鏈接來了解它所表示的意思........

通過用文本編輯工具打開通過Doxygen生成的配置文件，然後用Ctrl+F來查找相關的"設置詞彙"，來進行自定義，得到想要的文檔顯示格式

配置選項可以被分成幾類。下面給出的命令開關（或者說：配置選項）以字母順序給出：

配置選項可以被分成幾類。下面給出的命令開關（或者說：配置選項）以字母順序給出：

發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

linux服務器監控

1.load load爲特定時間間隔內運行隊列中平均線程數。load average後面三個值代表1、5、15分鐘系統的load值，如果每個cpu的線程數大於5，表示系統負載較高，需採取措施降低負載，加快系統響應速度。 $ upti

公子 2020-07-08 10:30:45

記一次網站備案

用了幾個月的免費AWS，感覺非常好用，Amazon的技術實力確實一流，但是最近速度變得非常慢，也不知道是什麼原因，於是就買了阿里雲的雲主機，那就得備案啊。很多人都是談備案色變，論壇中也是一片罵孃的聲音，感覺我是在這麼一個恐怖的環境下開始的

newborn2012 2020-07-08 08:17:30

那些年我們一起敲過的機房收費系統——完結篇

引言    不知不覺，我在機房收費系統上耗的時間也有兩個月多了，很尷尬，就像我們的故事一樣，摻雜了太多感情在裏面了，但是地球總還是要轉的，明天早上太陽依然還是要升起的，所以這件事還是要有個完結的，所以今天我們就再此寫下此完結篇，臨表嗟嘆

bink_linda 2020-07-08 03:53:02

華爲Mate30網絡拒絕接入wifi問題 ，解決動態MAC白名單限制（新手機連接不了公司WIFI網絡解決方法）

華爲Mate30網絡拒絕接入wifi問題 ，解決動態MAC白名單限制       由於公司對WIFI接入管控比較嚴格，路由器設置了MAC地址過濾，只允許白名單MAC地址接入，對於公司同事新入手華爲mate30 Pro 5G 的用戶，需要做

sunfor 2020-07-07 23:14:55

超聲波指紋識別技術

前言： 2015年，整個超聲技術界最引人注目的事情莫過於高通推出了超聲波指紋識別技術Sense ID，而小米手機也成功搭載了這一項黑科技。自上世紀五十年代全國超聲熱之後，超聲技術終於有機會成爲大衆話題之一 超聲檢測技術基礎之基礎

liyongqi_ 2020-07-07 12:07:09

word使用過程中遇到的問題記錄（二）：如何畫柱狀圖和折線圖的組合圖？

最近在寫一些報告，要用到不少表格和圖，一開始不知道如何畫柱狀圖和折線圖的結合體，查了一番後搞定，記錄下，以備日後翻閱。 以GDP的數據爲例說明： 1、在word中插入一張柱狀圖表，會自動生成一個excel，用來填寫數據，如下圖所示： 根

芸轩 2020-07-07 00:53:20

【創業】華爲那一套不是處處喫香

有2年了，幾個朋友都是華爲的，40上下，公司發展一般，心有不甘，談到創業，硬是找了個路子去做。2年下來，真是狗血劇。基本上把電視劇裏能想到的橋段都出現了。給朋友們一饗，提個醒，也算沒白乾。1)不要把創業代替就業我這兩年，感覺到周圍的朋友，

zhangling61130 2020-07-06 22:09:02

您適合從事web前端開發嗎？

 隨着互聯網的迅猛發展和普及，一個新型的行業和新興的職位正在上升到技術的層面：web前端開發工程師。一些想從事、或感興趣的人會問：我適合做前端工程師嗎？什麼樣的人最合適？ 首先，我們看一下前端新人從哪裏來？相對於其他IT技術職位來說，

东方潮汐 2020-07-06 18:05:44

淺談雲計算的形態

 原文：淺談雲計算的形態 這幾年雲計算概念炒的很火熱，不僅是很多的雲計算相關的創業公司如雨後春筍般冒出來，大佬們也紛紛加入戰場。IaaS、PaaS、SaaS、BaaS多種形態並存，一派繁榮景象。本文結合自己的理解對目前市面上的雲計算形

东方潮汐 2020-07-06 18:05:34

sql server 不允許保存更改，您所做的更改要求刪除並重新創建以下表 的解決辦法

原文地址 啓動SQL Server Management Studio 工具菜單—-選項—-Designers(設計器)—-阻止保存要求重新創建表的更改 取消勾選即可。

诗人江湖老 2020-07-06 13:25:13

Timeout 時間已到。在操作完成之前超時時間已過或服務器未響應。 (.Net SqlClient Data Provider)

　　原文地址 　　在做一個小東西的時候出現了這個問題,就是使用VS調試幾次項目後,使用SQL Server Management Studio管理數據庫時,使用SA登錄就會出現這個錯誤,當然,如果項目中的數據庫連接字符串中使用的

诗人江湖老 2020-07-06 13:25:13

自然用戶界面

自然用戶界面（英語：Natural user interface, NUI）是指一類無形的用戶界面。 “自然”一詞是相對圖形用戶界面（GUI）而言的，GUI要求用戶必須先學習軟件開發者預先設置好的操作，而NUI則只需要人們以最自然的交流方

Smile_路飞 2020-07-06 03:58:01

網站部署不成功——Win7 64位 IIS未能加載文件或程序集“System.Data.SQLite”或它的某一個依賴項

系統部署失敗。 原因：未能加載文件或程序集“System.Data.SQLite”或它的某一個依賴項 解決方案： 1、需要在IIS裏設置，設置應用程序池——啓用32位應用程序  把啓用32位應用程序的false改爲true2、下載 Sy

战神 2020-07-05 20:57:23

免費開源項目管理軟件介紹

       現在開源的項目管理軟件可謂五花八門，很多人都不知道如何去選擇一個項目管理軟件。一個真正好的項目管理軟件，只能是針對自己要管理的內容來說的。很多時候我們看了那些軟件的介紹還是無從選取。下面我對比較流行的項目管理軟件用一個圖表來

战神 2020-07-05 20:57:23

一些知識收集

  C# String與byte[]之間轉換  http://developer.51cto.com/art/200908/148342.htm s

thebigbird 2020-07-05 17:01:03