開始使用

可執行檔 doxygen 是主要程式,會解析原始碼並產生文件。如需更詳細的使用資訊,請參閱 Doxygen 使用方式 章節。

或者,也可以使用可執行檔 doxywizard,這是一個 圖形化前端介面,可用於編輯 Doxygen 使用的組態檔,並在圖形環境中執行 Doxygen。在 macOS 上,點擊 Doxygen 應用程式圖示即可啟動 Doxywizard。

下圖顯示了工具之間的關係以及它們之間資訊的流動方式(看起來很複雜,但這只是因為它試圖盡可能完整)

Doxygen 資訊流

步驟 0:檢查 Doxygen 是否支援您的程式/硬體描述語言

首先,請確認您的程式/硬體描述語言有相當大的機率會被 Doxygen 識別。預設支援的程式語言包括:C、C++、Lex、C#、Objective-C、IDL、Java、PHP、Python、Fortran 和 D。Doxygen 預設也支援硬體描述語言 VHDL。可以設定某些檔案類型副檔名來使用特定的剖析器:詳情請參閱 組態/擴充功能對應。此外,也可以使用前置處理器程式來支援完全不同的語言:詳情請參閱 協助工具頁面

步驟 1:建立組態檔

Doxygen 使用組態檔來決定其所有設定。每個專案都應有自己的組態檔。一個專案可以只包含一個原始碼檔案,但也可能是一個遞迴掃描的整個原始碼樹狀結構。

為了簡化組態檔的建立,Doxygen 可以為您建立範本組態檔。若要執行此操作,請從命令列使用 -g 選項呼叫 doxygen

doxygen -g <config-file>

其中 <config-file> 是組態檔的名稱。如果您省略檔案名稱,則會建立名為 Doxyfile 的檔案。如果已存在名為 <config-file> 的檔案,Doxygen 會先將其重新命名為 <config-file>.bak,然後再產生組態範本。如果您使用 -(即減號)作為檔案名稱,則 Doxygen 會嘗試從標準輸入 (stdin) 讀取組態檔,這對於腳本編寫很有用。

組態檔的格式與(簡單的)Makefile 相似。它由許多形式為

TAGNAME = VALUE
TAGNAME = VALUE1 VALUE2 ...

的賦值(標籤)組成。您可能會希望將大多數標籤的值保留在產生的範本組態檔中的預設值。有關組態檔的更多詳細資訊,請參閱 組態 章節。

如果您不想使用文字編輯器編輯組態檔,則應查看 Doxywizard,這是一個 GUI 前端介面,可以建立、讀取和寫入 Doxygen 組態檔,並允許透過對話方塊輸入組態選項來設定它們。

對於由少數 C 和/或 C++ 原始碼和標頭檔組成的小型專案,您可以將 INPUT 標籤留空,Doxygen 將會在目前目錄中搜尋原始碼。

如果您有一個由原始碼目錄或樹狀結構組成的大型專案,則應將根目錄或多個目錄指派給 INPUT 標籤,並將一個或多個檔案模式新增至 FILE_PATTERNS 標籤(例如 *.cpp *.h)。只會剖析符合其中一個模式的檔案(如果省略模式,則會使用 Doxygen 支援的檔案類型典型模式清單)。若要遞迴剖析原始碼樹狀結構,您必須將 RECURSIVE 標籤設定為 YES。為了進一步微調剖析的檔案清單,可以使用 EXCLUDEEXCLUDE_PATTERNS 標籤。例如,若要從原始碼樹狀結構中省略所有 test 目錄,可以使用

EXCLUDE_PATTERNS = */test/*

Doxygen 會檢視檔案的副檔名以決定如何剖析檔案,使用下表

副檔名語言副檔名語言副檔名語言
.doxC / C++.HHC / C++.pyPython
.docC / C++.hxxC / C++.pywPython
.cC / C++.hppC / C++.fFortran
.ccC / C++.h++C / C++.forFortran
.cxxC / C++.mmC / C++.f90Fortran
.cppC / C++.txtC / C++.f95Fortran
.c++C / C++.idlIDL.f03Fortran
.cppmC / C++.ddlIDL.f08Fortran
.ccmC / C++.odlIDL.f18Fortran
.cxxmC / C++.javaJava.vhdVHDL
.c++mC / C++.csC#.vhdlVHDL
.iiC / C++.dD.ucfVHDL
.ixxC / C++.phpPHP.qsfVHDL
.ippC / C++.php4PHP.lLex
.i++C / C++.php5PHP.mdMarkdown
.inlC / C++.incPHP.markdownMarkdown
.hC / C++.phtmlPHP.iceSlice
.HC / C++.mObjective-C   
.hhC / C++.MObjective-C   

請注意,以上清單可能包含比 FILE_PATTERNS 中預設設定的項目還多。

任何未剖析的副檔名都可以透過將其新增至 FILE_PATTERNS 並設定適當的 EXTENSION_MAPPING 來設定。

如果您開始針對現有專案使用 Doxygen(因此沒有任何 Doxygen 已知的說明文件),您仍然可以瞭解其結構以及說明文件化的結果外觀。若要執行此操作,您必須將組態檔中的 EXTRACT_ALL 標籤設定為 YES。然後,Doxygen 將會假裝您原始碼中的所有內容都有說明文件。請注意,只要 EXTRACT_ALL 設定為 YES,就不會產生有關未說明文件成員的警告。

若要分析現有的軟體,將(說明文件化的)實體與原始碼檔案中的定義交叉參照很有用。如果您將 SOURCE_BROWSER 標籤設定為 YES,Doxygen 將會產生此類交叉參照。它也可以透過將 INLINE_SOURCES 設定為 YES,將原始碼直接包含在文件中(例如,這對於程式碼審查很有用)。

步驟 2:執行 Doxygen

若要產生文件,您現在可以輸入

doxygen <config-file>

根據您的設定,Doxygen 將會在輸出目錄內建立 htmlrtflatexxmlman 和/或 docbook 目錄。顧名思義,這些目錄包含 HTML、RTF、{\LaTeX}、XML、Unix Man page 和 DocBook 格式的產生文件。

預設輸出目錄是 doxygen 啟動所在的目錄。可以使用 OUTPUT_DIRECTORY 變更寫入輸出的根目錄。可以使用組態檔的 HTML_OUTPUTRTF_OUTPUTLATEX_OUTPUTXML_OUTPUTMAN_OUTPUTDOCBOOK_OUTPUT 標籤來選取輸出目錄中的特定格式目錄。如果輸出目錄不存在,doxygen 會嘗試為您建立它(但它不會嘗試遞迴建立整個路徑,例如 mkdir -p)。

HTML 輸出

可以透過將 HTML 瀏覽器指向 html 目錄中的 index.html 檔案來檢視產生的 HTML 文件。為了獲得最佳結果,應使用支援串聯樣式表 (CSS) 的瀏覽器(我使用 Mozilla Firefox、Google Chrome、Safari,有時還會使用 IE8、IE9 和 Opera 來測試產生的輸出)。

HTML 區段中的某些功能(例如 GENERATE_TREEVIEW 或搜尋引擎)需要支援動態 HTML 並啟用 JavaScript 的瀏覽器。

LaTeX 輸出

產生的 {\LaTeX} 文件必須先由 {\LaTeX} 編譯器編譯(我使用適用於 Linux 和 macOS 的最新 teTeX 發行版和適用於 Windows 的 MikTex)。為了簡化編譯產生文件的過程,doxygen 會將 Makefile 寫入 latex 目錄(在 Windows 平台上也會產生 make.bat 批次檔)。

Makefile 中的內容和目標取決於 USE_PDFLATEX 的設定。如果停用(設定為 NO),則在 latex 目錄中輸入 make 將會產生一個名為 refman.dvidvi 檔案。然後可以使用 xdvi 檢視此檔案,或透過輸入 make ps 將其轉換為 PostScript 檔案 refman.ps(這需要 dvips)。

若要將 2 頁放在一個實體頁面上,請改用 make ps_2on1。產生的 PostScript 檔案可以傳送到 PostScript 印表機。如果您沒有 PostScript 印表機,您可以嘗試使用 ghostscript 將 PostScript 轉換為您的印表機能夠理解的格式。

如果您已安裝 ghostscript 解譯器,也可以轉換為 PDF;只需輸入 make pdf(或 make pdf_2on1)。

若要取得 PDF 輸出的最佳結果,您應將 PDF_HYPERLINKSUSE_PDFLATEX 標籤設定為 YES。在此情況下,Makefile 將只會包含一個直接建置 refman.pdf 的目標。

RTF 輸出

Doxygen 會將 RTF 輸出合併為一個名為 refman.rtf 的單一檔案。此檔案已針對匯入 Microsoft Word 進行最佳化。某些資訊會使用所謂的欄位進行編碼。若要顯示實際值,您需要選取所有內容(編輯 - 全選),然後切換欄位(按一下滑鼠右鍵並從下拉式選單中選取選項)。

XML 輸出

XML 輸出包含 Doxygen 收集的資訊的結構化「傾印」。每個複合項目(類別/命名空間/檔案/...)都有自己的 XML 檔案,並且還有一個名為 index.xml 的索引檔案。

也會產生一個名為 combine.xslt 的 XSLT 腳本,可用於將所有 XML 檔案合併為單一檔案。

Doxygen 也會產生兩個 XML 綱要檔案 index.xsd(用於索引檔案)和 compound.xsd(用於複合檔案)。此綱要檔案描述可能的元素、其屬性以及它們的結構方式,也就是說,它描述 XML 檔案的語法,可用於驗證或引導 XSLT 腳本。

addon/doxmlparser 目錄中,您可以找到一個剖析器函式庫,用於以遞增的方式讀取 Doxygen 產生的 XML 輸出(請參閱 addon/doxmlparser/doxmparser/index.pyaddon/doxmlparser/doxmlparser/compound.py 以了解函式庫的介面)

Man 頁面輸出

可以使用 man 程式檢視產生的 man 頁面。您確實需要確保 man 目錄位於 man 路徑中(請參閱 MANPATH 環境變數)。請注意,man 頁面格式的功能有一些限制,因此某些資訊(例如類別圖、交叉參考和公式)將會遺失。

DocBook 輸出

Doxygen 也可以產生 DocBook 格式的輸出。如何處理 DocBook 輸出不在本手冊的範圍內。

步驟 3:撰寫原始碼文件

雖然撰寫原始碼文件是作為步驟 3 呈現,但在一個新的專案中,這當然應該是步驟 1。在這裡,我假設您已經有一些程式碼,並且您希望 Doxygen 產生一份說明 API 和可能內部結構以及一些相關設計文件的精美文件。

如果設定檔中的 EXTRACT_ALL 選項設定為 NO(預設值),則 Doxygen 只會為「有文件」的實體產生文件。那麼您要如何為這些實體撰寫文件呢?對於成員、類別和命名空間,基本上有兩種選擇

  1. 在成員、類別或命名空間的宣告或定義前面放置一個特殊的文件區塊。對於檔案、類別和命名空間成員,也允許將文件直接放置在成員之後。

    請參閱 特殊註解區塊 章節,以了解有關特殊文件區塊的更多資訊。

  2. 將特殊文件區塊放置在其他位置(另一個檔案或其他位置),在文件區塊中放置一個結構命令。結構命令會將文件區塊連結到可以記錄的特定實體(例如成員、類別、命名空間或檔案)。

    請參閱 其他位置的文件 章節,以了解有關結構命令的更多資訊。

第一個選項的優點是您不必重複實體的名稱。

檔案只能使用第二個選項來記錄,因為沒有辦法在檔案之前放置文件區塊。當然,檔案成員(函數、變數、typedef、define)不需要明確的結構命令;只要將特殊文件區塊放置在其前面或後面就可以正常運作。

特殊文件區塊內的文字會在寫入 HTML 和/或 {\LaTeX} 輸出檔案之前進行剖析。

在剖析期間,會執行下列步驟

  • Markdown 格式會由對應的 HTML 或特殊命令取代。
  • 文件內的特殊命令會被執行。請參閱 特殊命令 章節以取得所有命令的概述。
  • 如果一行以一些空白符號開頭,後面接著一或多個星號 (*),然後選擇性地接著更多空白符號,則會移除所有空白符號和星號。
  • 所有產生的空白行都會被視為段落分隔符號。這可讓您不必自己放置新段落命令,即可使產生的文件可讀。
  • 會為對應於有文件的類別的單字建立連結(除非該單字前面有 %;則該單字不會連結,並且會移除 % 符號)。
  • 當在文字中找到特定模式時,會建立指向成員的連結。請參閱 自動連結產生 章節,以了解有關自動連結產生如何運作的更多資訊。
  • 文件中的 HTML 標籤會被解譯,並轉換為 {\LaTeX} 輸出的 {\LaTeX} 等效標籤。請參閱 HTML 命令 章節,以取得所有支援的 HTML 標籤的概述。

前往 下一 章節,或返回 索引