緣起

在搜索dot和Graphviz時，看到doxygen，瞭解doxygen利用dot來繪製方法的關係圖。後來，在fish(friend interactive shell)的幫助文檔時，看到文檔是由doxygen生成的。很好奇，doxygen居然可以生成html文檔，就做了一下資料收集，整理出這麼個文檔出來。

正文

1. Doxygen簡介

Doxygen是一種開源跨平臺的，以類似JavaDoc風格描述的文檔系統，完全支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。註釋的語法與Qt-Doc、KDoc和JavaDoc兼容。其可以提供三個方面的幫助：

1.它可以從一組帶有文檔(即註釋)的源文件中生成在線文檔（HTML格式），或者離線參考手冊（LATEX格式）。同時還支持生成RTF（MS-Word）、Postscript、PDF、壓縮的HTML和UNIX man手冊。文檔是從源文件註釋中直接提取的，從而十分容易保持文檔和源碼的一致。

2.doxygen可配置，用以從沒有標註文檔的源文件中提取代碼結構。這對於要在大量源文件中快速地找到所需的東西來說是非常有用的。通過包含依賴圖（include dependency graphs）、繼承圖（inheritance diagram）和協作圖（collaboration diagram）等手段（它們都是自動生成的），可以使不同成分之間的關係可視化。

3.還可以“濫用”doxygen，創建普通文檔。”

一個好的程序員在寫程序時，都會在適當的地方加上合適的批註。如果以符合某種格式的方式撰寫批註，就能使用工具程序依據程序結構及批註產生出漂亮的文檔。

2. 支持語言和格式

支持的語言:C/C++,Java,Objective-C,Python,IDL (Corba, Microsoft及KDE-DCOP類型),Fortran,VHDL(一種硬件描述語言),PHP,C#

備註：Ruby的問檔工具爲Rdoc

輸出格式: HTML，XML，LaTeX（間接支持PDF），RTF (MS-Word)，PostScript，Unix Man Page

3. 安裝

Ubuntu/debian:sudo apt-get install doxygen

官方下載二進制包（Linux，windows，Mac os各種平臺在官方網站都有的下）或源碼編譯（./configure-->make-->make install）。源碼編譯可能比較麻煩，存在一些前置條件：graphviz，flex，python，make以及g++之類的工具。不過我編譯的時候，沒有出現問題，那些前置條件恰好都滿足，遇到不滿足的，apt-get install就行了。

4. 簡單使用

Doxygen使用可以分爲兩個部分：1.特定格式的註釋的撰寫（主要工作） 2.利用Doxygen工具來生成文檔

下面首先介紹Doxygen支持的註釋格式，然後介紹如何使用doxygen來生成文檔。

4.1. 編寫註釋

一般而言，要爲每個類、以及該類的重要成員函數增加短註釋和長註釋。短註釋應給出類或函數的基本信息的簡要描述。而較長的註釋給出更長和更完整的描述。類的短註釋和長註釋，以及成員函數的簡短描述，將放在頭文件中。成員函數的長註釋將出現在成員函數的實現出現的地方。

4.1.1. 註釋風格

使用doxygen的第一步是在代碼中插入doxygen風格的註釋。代碼附加的註釋塊通常由一行或多行組成，其中包含一個概要說明和詳細說明，可以使用多種不同風格的doxygen註釋：

1)JavaDoc類型的多行註釋

/**

* ... text ...

2)Qt風格的多行註釋：

/*!

...text...

3)單行註釋：

//! ... one line of text ...

/// ... one line of text ...

http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v1/class_CsICluster.html提供一個可參照的樣例HTML文檔。

4.1.2. 常用註釋格式

通常的選擇上面的一、兩種註釋風格,遇到頭文件中各種類型定義,關鍵變量、宏的定義,在其前或者後使用@brief定義其簡要說明,空一行後繼續寫其詳細的註釋即可。

函數是需要註釋說明的部分。除了定義其簡要說明以及詳細註釋,還可以使用param命令對其各個參數進行註釋,使用return命令對返回值進行註釋。函數的參數格式如下:

格式1:

/**
<A short one line description>
 
<Longer description>
<May span multiple lines or paragraphs as needed>
 
@param  Description of method's or function's input parameter
@param  ...
@return Description of the return value
*/

格式2:

/**
 * <A short one line description>
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  Description of method's or function's input parameter
 * @param  ...
 * @return Description of the return value
 */

格式3:

/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @param  Description of method's or function's input parameter
/// @param  ...
/// @return Description of the return value

C++中常使用的格式：

/**
 * @file
 * @author  John Doe <[email protected]>
 * @version 1.0
 *
 * @section LICENSE
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details at
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @section DESCRIPTION
 *
 * The time class represents a moment of time.
 */
class Time {
 
    public:
       /**
        * Constructor that sets the time to a given value.
        *
        * @param timemillis Number of milliseconds
        *        passed since Jan 1, 1970.
        */
       Time (int timemillis) {
           // the code
       }
       /**
        * Get the current time.
        *
        * @return A time object set to the current time.
        */
       static Time now () {
           // the code
       }
};

進行設計時,通常有模塊的概念,一個模塊可能有多個類或者函數組成,完成某個特定功能的代碼的集合。爲了這個概念進行註釋，doxygen提供了group命令,生成的模塊的註釋會單獨放在一個模塊的頁面中。使用下面的格式定義一個group。

group中的代碼可以有自己的註釋。單純定義一個模塊,去除{ 和}命令即可。任何其他代碼項(比如類、函數、甚至文件)如果要加入到某個模塊,可以在其doxygen註釋中使用ingroup命令即可。Group之間使用ingroup命令,可以組成樹狀關係。

將多個代碼項一起添加到某個模塊中可以使用addtogroup命令,格式和defgroup相似。對於某幾個功能類似的代碼項(比如類、函數、變量)等,如果希望一起添加註釋,而又不想提升到模塊的概念,可以通過下面的方式:

//@{

code...

//@}

4.1.3. 常用註釋命令

doxygen通過註釋命令識別註釋中需要特殊處理的註釋,比如函數的參數、返回值進行突出顯示。上面也提到了一些註釋命令(如:brief、param、return、以及group相關的命令),命令都以'\'或'@'開始,二者無區別,下面對其他一些常用的註釋命令進行解釋說明：

@exception <exception-object> {exception description} 對一個異常對象進行註釋。

@warning {warning message } 一些需要注意的事情

@todo { things to be done } 對將要做的事情進行註釋

@see {comment with reference to other items } 一段包含其他部分引用的註釋,中間包含對其他代碼項的名稱,自動產生對其的引用鏈接。

@relates <name> 通常用做把非成員函數的註釋文檔包含在類的說明文檔中。

@since {text} 通常用來說明從什麼版本、時間寫此部分代碼。

@deprecated

@pre { description of the precondition } 用來說明代碼項的前提條件。

@post { description of the postcondition } 用來說明代碼項之後的使用條件。

@code 在註釋中開始說明一段代碼,直到@endcode命令。

@endcode 註釋中代碼段的結束。

在doxygen中有一些特殊命令用來增強所生成的文檔。

\author 說明作者

\mainpage 指定用以填充主頁面的註釋的內容。

\section 指定章節信息。

\image 在你的文檔中插入圖像，可以用在任何註釋中。其語法如下所示：

\image html mypicture.gif

注意：doxygen通過IMAGE_PATH的變量在指定的目錄中查找圖像文件，且並非所有格式都支持所有的圖像類型。

到此爲止,常用的doxygen的註釋格式討論完畢,可以按照一定的格式撰寫doxygen識別的註釋,不過註釋中應該寫些什麼,如何撰寫有效的註釋？

4.1.4. 註釋的書寫

註釋應該怎麼寫,寫多還是寫少。過多的註釋甚至會干擾對代碼的閱讀，過少又不足以解釋清楚。寫註釋的一個總的原則就是註釋應該儘量用來表明作者的意圖,從解決問題的層次上進行註釋,而是重複性介紹一些顯然易見的東西。

寫註釋的過程是首先使用註釋勾勒出代碼的主要框架,然後根據註釋撰寫相應的代碼。對各種主要的數據結構、輸出的函數、多個函數公用的變量進行詳細地註釋。對代碼中控制結構,單一目的的語句集進行註釋。下面是一些寫註釋時需要注意的要點:

l 避免對單獨語句進行註釋;
l 通過註釋解釋爲什麼這麼做、或者要做什麼,使代碼的讀者可以只閱讀註釋理解代碼;
l 對讀者可能會有疑問的地方進行註釋;
l 對數據定義進行註釋,而不是對其使用過程進行註釋;
l 對於難於理解的代碼,進行改寫,而不要試圖通過註釋加以說明;
l 對關鍵的控制結構進行註釋;
l 對數據和函數的邊界、使用前提等進行註釋;

4.2. 生成文檔

Doxygen的生成文檔的步驟非常簡單:

1)使用doxygen生成一個配置文件的模板：

doxygen [-s] -g [configName]

如果configName是'-'那麼doxygen將會把結果寫到標準輸出。

2)使用doxygen更新舊的配置文件：

doxygen [-s] -u [configName]

3)根據已經存在的配置文件，使用doxygen生成文檔：

doxygen [configName]

如果configName是'-'那麼doxygen將會從標準輸入讀取配置信息。

4)使用doxygen生成RTF,HTML,或者Latex風格的模板文件:

RTF格式：doxygen -w rtf styleSheetFile

HTML格式：doxygen -w html headerFile footerFile styleSheetFile [configFile]

LaTex格式:doxygen -w latex headerFile styleSheetFile [configFile]

5)使用doxygen生成rtf擴展文件？？

RTF格式：doxygen -e rtf extensionsFile

如果指定了-s那麼配置文件中的註釋將會被忽略。如果配置名被忽略了，那麼'Doxy-file'將被做爲默認的文件使用。

安裝doxygen-doc會獲得如何使用doxygen的更多信息(即$sudo apt-get install doxygen-doc)。可以查看/usr/share/doc/doxygen。

使用Doxyfile時需要設置一些參數。這裏三個有趣的參數，其他的請參考doxygen的配置文件。

● INPUT：此參數指定doxygen在其中搜索源碼的目錄。

● FILE_PATTERNS：此參數指定doxygen所要解析的文件的類型。

● IMAGE_PATH：此參數指定doxygen在哪裏查找使用/image命令包含的圖像。

設置完參數就可以運行doxygen。假定配置文件爲Doxyfile，執行

doxygen Doxyfile

doxygen將解析你指定的所有文件。缺省地，HTML輸出將被放在叫作html/的目錄中（這也可在Doxyfile中改變）。

4.2.1. Doxygen的配置文件

Doxygen在生成文檔時存在很多可配置的選項，doxygen -g可以生成缺省的配置文件。doxygen配置文件的格式爲unix下配置文件的格式:

l 註釋'#'開始;

l tag = value[,value2...];

l 對於多值的情況可以使用 tag += value [,value2...]。

對doxygen的配置文件的修改分爲兩類:一種就是輸出選項,控制如何解釋源代碼、如何輸出;一種就是項目或程序相關的信息,比如項目名稱、源代碼目錄、輸出文檔目錄等。對於第一種配置,通常所有項目可以共用相同的配置,而第二種配置是每個項目或程序必須設置的。下面選擇重要的,有可能需要修改的選項進行解釋說明,其他選項在配置文件都有詳細解釋。

TAG	缺省值	含義
PROJECT_NAME		項目名稱
PROJECT_NUMBER		可以理解爲版本信息
OUTPUT_DIRECTORY		輸出文件到的目錄,相對目錄(doxygen運行目錄)或者絕對目錄
INPUT		代碼文件或者代碼所在目錄,使用空格分割
FILE_PATTERNS	.c .cc .cxx .cpp .c++ .java .ii .ixx .ipp .i++ .inl .h.hh .hxx .hpp .h++ .idl .odl	指定INPUT的目錄中特定文件,如:.cpp .c *.h
RECURSIVE	NO	是否遞歸INPUT中目錄的子目錄
EXCLUDE		在INPUT目錄中需要忽略的子目錄
EXCLUDE_PATTERNS		明確指定的在INPUT目錄中需要忽略的文件,如:FromOut*.cpp
OUTPUT_LANGUAGE		English 生成文檔的語言,當前支持2、30種語言,國內用戶可以設置爲Chinese
DOXYFILE_ENCODING	UTF-8	文件編碼格式
EXTRACT_ALL	NO	爲NO,只解釋有doxygen格式註釋的代碼;爲YES,解析所有代碼,即使沒有註釋。類的私有成員和所有的靜態項由EXTRACT_PRIVATE和 EXTRACT_STATIC控制
EXTRACT_PRIVATE	NO	是否解析類的私有成員
EXTRACT_STATIC	NO	是否解析靜態項
EXTRACT_LOCAL_CLASSES	YES	是否解析源文件(cpp文件)中定義的類
SOURCE_BROWSER	NO	如果爲YES,源代碼文件會被包含在文檔中
INLINE_SOURCES	NO	如果爲YES,函數和類的實現代碼被包含在文檔中
ALPHABETICAL_INDEX	NO	生成一個字母序的列表,有很多類、結構等項時建議設爲YES
GENERATE_HTML	YES	是否生成HTML格式文檔
GENERATE_HTMLHELP	NO	是否生成壓縮HTML格式文檔(.chm)
GENERATE_LATEX	YES	是否生成latex格式的文檔
GENERATE_RTF	NO	是否生成RTF格式的文檔
GENERATE_MAN	NO	是否生成man格式文檔
GENERATE_XML	NO	是否生成XML格式文檔

4.3. 使用實例

下面使用一個簡單的例子來測試Doxygen，程序的結構是

./src/main.cpp

./src/subModule/myClass.h

./src/main.cpp

./lib/say.h

./lib/say.cpp

可下載測試文件的鏈接爲: test.zip

使用命令doxygen -g test 生成名爲test的doxygen配置文件，對其中的配置項作出如下修改:

#給出所有文檔的輸出目錄

OUTPUT_DIRECTORY = doc

#設置使用的語言

OUTPUT_LANGUAGE = Chinese

#生成chm格式的壓縮html文檔

GENERATE_HTMLHELP = YES

#生成latex文檔

GENERATE_LATEX = YES

#指定doxygen分析的輸入文件(目錄)

INPUT = src lib

#指定分析的文件的類型（擴展名）

INCLUDE_FILE_PATTERNS = *.cpp *.h

#遞歸查找INPUT中的文件

RECURSIVE = YES

#處理完一個函數的文檔之後，對函數調用的函數也列出相關的鏈接。

REFERENCES_RELATION = YES

截圖顯示:

Html結果展示:

5. 進一步閱讀

Doxygen使用總結:http://blog.chinaunix.net/uid-9525959-id-2001574.html

Doxygen中文手冊（1.63）:http://wenku.baidu.com/view/3b33690f33687e21af45a9c0.html

Doxygen官方主頁:http://www.stack.nl/~dimitri/doxygen/

開發主頁（Github）https://github.com/doxygen/doxygen

總結

Doxygen還是比較的強大的工具，花了很長時間來學習和了解這個工具。此外，自己下載源代碼編譯還是很有用處的，可以自己編譯文檔之類的，如果編譯成功確實不錯，但是失敗的時候，也挺令人沮喪的。

有時候，覺得自己寫的相關的主題的東西網上很氾濫，何必再增加重複信息。本着記錄探索的過程的方式，我還是寫了關於這個主題的博客，也有介紹自己的動機，並且還自認爲自己寫的不錯（請原諒我的自戀）。

最近，寫博客的方式是先在WPS（Linux版）中編寫，然後複製到csdn的博客中。本地doc的文檔的排版要比博客上的排版好，這裏提供一個pdf版下載鏈接：關於Doxygen。

參考文獻

1. Doxygen使用:http://blog.csdn.net/yuantao/article/details/402207

2. Doxygen使用總結:http://blog.chinaunix.net/uid-9525959-id-2001574.html

3. Doxygen中文手冊（1.63）:http://wenku.baidu.com/view/3b33690f33687e21af45a9c0.html

4. doxygen使用詳解:http://wenku.baidu.com/view/3ad26a4279563c1ec5da71b7.html

xiajian2010

發佈了66 篇原創文章 · 獲贊 18 · 訪問量 28萬+

私信關注

關於Doxygen

緣起

正文

1. Doxygen簡介

2. 支持語言和格式

3. 安裝

4. 簡單使用

4.1. 編寫註釋

4.1.1. 註釋風格

4.1.2. 常用註釋格式

4.1.3. 常用註釋命令

4.1.4. 註釋的書寫

4.2. 生成文檔

4.2.1. Doxygen的配置文件

4.3. 使用實例

5. 進一步閱讀

總結

參考文獻

Python實現大麥網搶票的四大關鍵技術點解析

salesforce零基礎學習（一百三十八）零碎知識點小總結（十）

一款開源的.NET程序集反編譯、編輯和調試神器

關於接口協議，你必須要知道這些！

【2024-05-21】以茶會友

關於輸入法的工作原理及編程

Ubuntu下的繪圖軟件

關於apt和aptitude

關於Mysql開機自啓動和Runlevel

Graphviz的使用及中文亂碼問題

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結