Doxygen文檔生成工具介紹

Doxygen是API文檔生成工具，可以根據(jù)代碼注釋生成文檔的工具。支持HTML、CHM、PDF等格式。主要支持C語言、Python語言，其它C語系語言也支持（如C++、Java、C#等）。

第1章 安裝

在Linux下可以通過apt install doxygen安裝命令行工具，然后用apt install doxygen-gui安裝圖形界面。對Linux用戶來說，命令行工具可以通過doxygen命令運(yùn)行，而圖形界面可以通過doxywizard命令運(yùn)行。

而Windows用戶可以在這里下載，安裝完畢后，直接雙擊就能運(yùn)行圖形界面。

1.1 基本使用

圖形工具的基本使用如圖1-1、圖1-2所示，有非常多的配置選項(xiàng)，這里我們只填入必要的配置，其它配置都用默認(rèn)值。

image
image

我們的工作目錄如下：

.
├── out
└── src
    └── math.h

其中math.h代碼如下：

/*! \file math.h */

/*!
    用于求一個角度的sin值，輸入是字符串以便同時支持弧度制和角度制表示
    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
    \li 角度制用d結(jié)尾，例如：360d表示一圈、90d表示直角
    \li 輸入也可以是數(shù)值，例如：輸入3.14159大約表示180度

    \param a 用弧度制或角度制表示都行，字符串必須用'\0'表示結(jié)束
    \param[out] res 是輸出參數(shù)，用于保存sin運(yùn)算的結(jié)果

    \return 錯誤碼，0表示成功，其它表示失敗

    \todo 在xxx的情況下存在BUG，預(yù)計(jì)下一版本修復(fù)
*/
int sin(char *a, double *res);

Doxygen生成的HTML會放到out目錄下，生成的HTML如圖1-3所示。

image

1.2 保存配置

在1.1節(jié)中我們配置了一些選項(xiàng)，也成功生成了HTML文檔。我們希望下次代碼改動后能夠繼續(xù)沿用上次配置，那么我們可以把這些配置保存成Doxyfile文件，見圖1-4。

image

1.3 命令行運(yùn)行Doxygen

有了配置文件后我們完全可以通過命令行來生成API文檔，假設(shè)配置文件名為Doxyfile，那么我們只需要執(zhí)行doxygen /path/to/Doxyfile即可生成API文檔。

通過命令行生成文檔有許多好處，其中最主要的好處就是：能夠集成到持續(xù)集成之類的自動化系統(tǒng)中。

第2章 為代碼編寫注釋

2.1 什么樣的注釋會被Doxygen識別？

Doxygen能識別這幾種風(fēng)格的注釋：

/**
 * ... text ...
 */

/*!
 * ... text ...
 */

///
/// ... text ...
///

//!
//!... text ...
//!

文件的開頭必須有文件注釋，否則該文件不會被識別：

/*! \file math.h */

2.2 注釋怎么寫

這個自己看官網(wǎng)例子體會吧。

第3章 為其它編程語言生成注釋

Doxygen主要支持C語言，其它語法跟C差不多的語言（如：C++/C#/PHP/Java）也能夠支持，我們稱這類語言為「C語系語言」。而哪些跟C語法差異較大的語言叫做「非C語系語言」。

對于大多非C語系語言，Doxygen都是支持的，Doxygen原生支持這些語言：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

萬一項(xiàng)目需要的語言（例如：Lua）Doxygen官方并不支持，那么只能自行編寫「第三方語言擴(kuò)展」來支持了。

3.1 Doxygen官方支持的語言

見圖3-1，文件名符合FILE_PATTERNS都會被處理。其中包括了.c、.h、.py等等。

image

如果我們的擴(kuò)展名并不在FILE_PATTERNS內(nèi)，那么可以加上去。例如我們項(xiàng)目下的所有.ccc文件，其實(shí)是C語言代碼（這很奇葩，舉個例子而已）。那我們可以編輯Doxyfile配置文件滿足這一需求，需要2個步驟。

(1) 在FILE_PATTERNS中添加*.ccc，如圖3-2

image

(2) 在EXTENSION_MAPPING中添加映射規(guī)則ccc=C，如圖3-3。語法是ext=language，其中l(wèi)anguage可以取的值有：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

image

3.2 Doxygen官方不支持的語言

以Lua語言為例，它的代碼是長這樣的：

-- \file lmath.h

--[[
    用于求一個角度的sin值，輸入是字符串以便同時支持弧度制和角度制表示
    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
    \li 角度制用d結(jié)尾，例如：360d表示一圈、90d表示直角
    \li 輸入也可以是數(shù)值，例如：輸入3.14159大約表示180度

    \param a 字符串類型，表示角度，用弧度制或角度制表示都行

    \return 返回sin運(yùn)算的結(jié)果

    \todo 在xxx的情況下存在BUG，預(yù)計(jì)下一版本修復(fù)
--]]
function sin(a)
    return 1.123
end

可以看到Lua的語法既不像C也不像Python。本節(jié)以Lua為例，介紹如何為Doxygen編寫Lua語言擴(kuò)展。
好吧，大多數(shù)人沒有這種需求，這里就不介紹了。

第4章 定制Doxygen的輸出

4.1 定制頁面樣式

Doxygen輸出的默認(rèn)HTML比較難看，如圖4-1。

image

如果嫌生成的HTML不好看，可以自定義HTML頁面頭部、尾部以及頁面整體CSS樣式表。
(1) 生成默認(rèn)的風(fēng)格的配置文件，敲這個命令：doxygen -w html header.html footer.html customdoxygen.css，可以生成header.html、footer.html、customdoxygen.css。
(2) 根據(jù)自己的需求修改這三個文件。
(3) 配置HTML_HEADER、HTML_FOOTER、HTML_STYLESHEET指向修改后的文件，如圖4-2。

image

Doxygen默認(rèn)的頁面主色調(diào)大約是天藍(lán)色的，可以通過HTML_COLORSTYLE_HUE、HTML_COLORSTYLE_SAT、HTML_COLORSTYLE_GAMMA修改主色調(diào)，這3個配置分別對應(yīng)色相、飽和度、Gamma校正，見圖4-3。如果不太懂色相、飽和度是啥意思，請自行百度「色彩模式」或參考Photoshop相關(guān)教程。

image

經(jīng)過圖4-3的修改，頁面的主色調(diào)變?yōu)閳D4-4的樣子。

image

4.2 導(dǎo)航欄

Doxygen中「導(dǎo)航欄」有兩種展示方式：Treeview和Index，分別是豎向和橫向的，如圖4-5。

image

可以配置DISABLE_INDEX和GENERATE_TREEVIEW來控制是否顯示它們，如圖4-6。

image

4.3 自定義「導(dǎo)航欄」的目錄結(jié)構(gòu)

我們已經(jīng)知道Doxygen中「導(dǎo)航欄」有Treeview和Index兩種了。這節(jié)介紹如何定制導(dǎo)航欄的目錄結(jié)構(gòu)。這需要三個步驟。
(1) 執(zhí)行doxygen -l，生成DoxygenLayout.xml文件
(2) 編輯DoxygenLayout.xml文件，修改其中的布局
(3) 修改LAYOUT_FILE配置，使其指向DoxygenLayout.xml文件，如圖4-7
(4) 運(yùn)行Doxygen

image

那么如何修改XML文件呢？默認(rèn)的DoxygenLayout.xml代碼如下：

<doxygenlayout version="1.0">
  <navindex>
    <tab type="mainpage" visible="yes" title=""/>
    <tab type="pages" visible="yes" title="" intro=""/>
    <tab type="modules" visible="yes" title="" intro=""/>
    <tab type="namespaces" visible="yes" title="">
      <tab type="namespacelist" visible="yes" title="" intro=""/>
      <tab type="namespacemembers" visible="yes" title="" intro=""/>
    </tab>
    <tab type="classes" visible="yes" title="">
      <tab type="classlist" visible="yes" title="" intro=""/>
      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
      <tab type="hierarchy" visible="yes" title="" intro=""/>
      <tab type="classmembers" visible="yes" title="" intro=""/>
    </tab>
    <tab type="files" visible="yes" title="">
      <tab type="filelist" visible="yes" title="" intro=""/>
      <tab type="globals" visible="yes" title="" intro=""/>
    </tab>
    <tab type="examples" visible="yes" title="" intro=""/>  
  </navindex>
</doxygenlayout>

XML對應(yīng)了導(dǎo)航欄的目錄樹結(jié)構(gòu)，我們通過該文件改變布局。標(biāo)簽的type屬性取值除了上面列出的這些預(yù)定義值以外，還可以是type="user"或type="usergroup"，我們只能通過這兩個type自定義布局，例如下面這段代碼，生成的效果如圖4-8：

<doxygenlayout version="1.0">
  <navindex>
    <tab type="usergroup" visible="yes" title="友情鏈接（演示如何外鏈）">
      <tab type="user" visible="yes" title="百度" url="http://www.baidu.com" />
      <tab type="user" visible="yes" title="163" url="http://www.163.com" />
    </tab>
    <tab type="usergroup" visible="yes" title="數(shù)學(xué)庫（演示如何鏈接文件）">
      <tab type="user" visible="yes" url="@ref math.h" title="math" />
      <tab type="user" visible="yes" url="@ref math2.h" title="math2" />
    </tab>
    <tab type="usergroup" visible="yes" title="三角函數(shù)（演示鏈接函數(shù)、結(jié)構(gòu)體）">
      <tab type="user" visible="yes" url="@ref sin" title="sin" />
      <tab type="user" visible="yes" url="@ref sin2" title="sin2" />
    </tab>
  </navindex>
</doxygenlayout>
image

4.4 完全自定義

如果Doxygen輸出的界面實(shí)在不入你的法眼，4.1~4.3介紹的定制化功能也不能徹底滿足你的需求。那么你需要根據(jù)Doxygen輸出的XML數(shù)據(jù)自行生成界面了。
(1) 將GENERATE_XML配置為YES
(2) 去輸出目錄尋找生成的XML文件，XML文件包括了函數(shù)信息、注釋信息等
(3) 自己寫程序讀取XML文件，并生成漂亮的文檔

轉(zhuǎn)載鏈接

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

友情鏈接更多精彩內(nèi)容