在 Linux 上用 Doxygen 生成源代碼文檔

Doxygen 是一款廣泛使用的開源文檔生成工具，它通過代碼注釋來生成文檔。

在試著熟悉別人的代碼時，你總希望他們留下的代碼注釋能對你理解代碼有所幫助。同理，無論為了自己還是其他人，編寫代碼時寫注釋是好習慣。所有編程語言都有專門的注釋語法，注釋可以是一個單詞、一行文字、甚至是一整段話。編譯器或解釋器處理源代碼時會忽略注釋。

注釋不能完全取代文檔，但是有方法可以使用注釋來生成文檔。Doxygen 是一個開源的文檔生成工具，它能夠根據代碼注釋生成 HTML 或 LaTeX 格式的文檔。Doxygen 讓你在不用額外操作的情況下創建代碼結構概覽。儘管 Doxygen 主要是用來給 C++ 生成文檔的，它對其它語言同樣適用，比如 C、Objective-C、 C#、 PHP、Java 和 Python 等。

要使用 Doxygen，你只需要在源代碼中使用 Doxygen 能夠識別的語法來寫注釋。Doxygen 會掃描源碼文件，然後根據這些特殊注釋生成 HTML 或 LaTeX 文檔。下面的示例項目會演示如何使用 Doxygen 注釋，以及文檔是如通過注釋生成出來的。示例代碼可從 GitHub 上獲得，本文中也將引用 Doxygen 手冊及文檔 的相關章節。

在 Linux 上安裝 Doxygen

在 Fedora 上可以通過軟體包的形式安裝 Doxygen。打開終端運行命令：

sudo dnf install doxygen

在基於 Debian 的操作系統上，可以通過以下命令來安裝：

sudo apt-get install doxygen

使用

安裝完 Doxygen 後，你需要在項目中按 Doxygen 可以識別的格式來注釋代碼，還要提供一個 Doxyfile 配置文件來控制 Doxygen 的一些行為。

注意：如果你用的是 GitHub 上的示例項目，你可以忽略下面一步。

如果 Doxyfile 文件不存在，你可以用 Doxygen 生成一個標準 Doxyfile 模板文件。切換到項目根目錄下，運行：

doxygen -g

參數 -g 表示 生成 generate 。現在應該會出現一個名為 Doxyfile 的新文件。通過命令調用 Doxygen：

doxygen

現在應該能會有兩個新文件夾：

• html/
• latex/

默認情況下，Doxygen 會同時輸出 LaTeX 和 HTML 格式的文檔。本文主要關注 HTML 文檔。你可以在 Doxygen 官方文檔的入門小節中找到關於 LaTeX 格式輸出的更多信息。

雙擊 html/index.html 打開 HTML 文件。用空的配置文件生成的文檔如下圖：

現在我們試著修改 Doxyfile 文件，並在源代碼中添加特殊注釋。

Doxyfile 文件

在 Doxyfile 文件中可以定義大量的可調選項，本文通過介紹示例項目的 Doxyfile 文件我只能覆蓋其中很小的子集。

第 35 行：項目名稱

你可以在這裡指定項目名稱，它最終會顯示在 頁眉 header 和瀏覽器標籤上。

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
# double-quotes, unless you are using Doxywizard) that should identify the
# project for which the documentation is generated. This name is used in the
# title of most generated pages and in a few other places.
# The default value is: My Project.

PROJECT_NAME           = "My Project"

第 47 行：項目簡介

項目簡介會以略小的字型大小顯示在頁眉上。

# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.

PROJECT_BRIEF          = "An example of using Doxygen in C++"

第 926 行：包含子目錄

允許 Doxygen 查找源代碼和文檔文件時遞歸遍歷子目錄。

# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
# The default value is: NO.

RECURSIVE = YES

第 1769 行：禁用 LaTeX 輸出

如果你只想生成 HTML 文檔，可以通過這個開關禁用 LaTeX 輸出。

# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.

# The default value is: YES.

GENERATE_LATEX = NO

修改完成後，你可以再次運行 Doxygen 來檢驗修改是否生效了。可以在調用 Doxygen 時使用 -x 選項來查看 Doxyfile 文件的變更項：

通過調用 diff 命令，Doxygen 僅顯示當前 Doxyfile 文件和模板文件的差異。

特殊注釋

Doxygen 通過掃描源代碼文件中的特殊注釋和關鍵字來生成 HTML 文檔。示例項目中的 ByteStream 類的頭文件可以很好地解釋特殊注釋的用法。

下面用構造函數和析構函數作為示例：

/*! @brief Constructor which takes an external buffer to operate on
*
* The specified buffer already exist.
* Memory and size can be accessed by buffer() and size().
*
* @param[in] pBuf Pointer to existing buffer
* @param[in] size Size of the existing buffer
*/

ByteStream(char* pBuf, size_t size) noexcept;

特殊注釋塊有不同的格式風格。我傾向於使用 /*! 開頭（Qt 風格），每行前添加 *，以 */ 結束注釋塊。你可以參考 Doxygen 手冊的文檔化代碼小節，以大致了解不同的風格選項。

Doxygen 注釋分兩個部分：簡要描述和詳細描述。它們都是可選的。在上面的例子中的注釋塊是對緊跟其後的構造函數聲明的描述。在 @brief 之後的文本會顯示在類概覽小節中：

在空行（空行是段落分隔符）之後是構造函數的實際文檔。用 @param[in/out] 關鍵字標註傳遞給構造函數的參數，Doxygen 基於此生成參數列表：

值得注意的是 Doxygen 為 buffer() 和 size() 方法自動生成了鏈接。相反，Doxygen 忽略了析構函數前的注釋，因為它並沒有使用特殊注釋：

// Destructor
~ByteStream();

現在你已經看到 Doxygen 的絕大部分功能了。通過使用一種稍微改良的注釋格式，讓 Doxygen 能夠識別它們。通過使用一些關鍵字，你甚至可以進一步控制格式化。在下一節中，我會進一步介紹 Doxygen 的其它特性。

其它特性

現在幾乎所有的工作都可以通過對源代碼注釋的方式完成。通過一些微調，你可以輕鬆地優化 Doxygen 的輸出。

Markdown 格式

為了進階的格式化，Doxygen 支持 Markdown 和 HTML 命令。Markdown 速查表可以在 這裡 下載到。

項目主頁

除了自定義頁眉之外，html/index.html 幾乎沒有其它內容了。你可以通過使用關鍵字向其中添加一些有意義的內容。因為主頁通常不是針對某個源代碼文件的，你可以將要顯示在主頁的內容放到項目根目錄下的一個單獨文件中。示例項目中就是這樣做的，其輸出效果如下：

自動鏈接生成

上面已將提到了，當你引用代碼的其它部分時，Doxygen 會自動識別並生成相應鏈接。但要注意，這要求被引用部分也有文檔才行。

更多信息可以在官方文檔的自動鏈接生成中找到。

分組

ByteStream 類 重載 overload 了的讀寫流操作符 （<< 和 >>）。在類的概覽中可以發現操作符被分為讀和寫兩組。分組是在 ByteStream 的頭文件中定義的。

分組的語法以標記 @{ 開始，以 }@ 結束。在標記範圍中的內容都屬於這個分組。在 ByteStream.h 中的實現如下：

/** @name Writing
* Operators for writing to the stream
* @{
*/

(...)

/** @}
* @name Reading
* Operators for reading from the stream
* @{
*/

(...)

/** @} */

你可以在官方文檔的分組中找到更多相關信息。

LLVM 支持

如果你用 Clang 構建項目的話，可以通過使用 -Wdocumentation 選項讓 Clang 對特殊注釋進行檢查。想了解該特性的更多信息，可以參考 LLVM 用戶手冊和 Dmitri Gribenko 的展示報告，它們可以在 Clang 網站上找到。

誰在用 Doxygen

Doxygen 是在 1997 年首次發布的。儘管有些年頭了，現在仍然有很多項目在使用 Doxygen。比如 NASA 的飛行軟體框架 F Prime、圖像處理庫 OpenCV、包管理器 RPM。你還可以在其它領域發現 Doxygen 語法標記的身影，比如內容管理平台 Drupal 的文檔標準中。

注意：Doxygen 輸出的 HTML 文檔風格類似於九十年代網頁。並且它也難以描繪元編程和模板編程架構。在這些情況下，你應該選擇 Sphinx 而不是 Doxygen。

（題圖：MJ/4d354094-397e-4ac5-a80d-25b9c736ede5）

via: https://opensource.com/article/22/5/document-source-code-doxygen-linux

作者：Stephan Avenwedde 選題：lkxed 譯者：toknow-gh 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive