在 Linux 上用 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 文件。用空的配置文件生成的文檔如下圖：
A screenshot of a doxygen generated main page on Firefox. The content field under My Project Documentation is blank.
現在我們試著修改 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 文件的變更項：
A screenshot of the terminal showing the differences, Project Name, Project Brief, Recursive, and status of Generate Latex
通過調用 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 之后的文本會顯示在類概覽小節中：
A screenshot of the C++ example of using Doxygen showing the Byte Stream Class Reference. The categories in the list are public member functions, writing (operators for writing to the stream), and reading (operators for reading from the stream)
A screenshot of the C++ example of using Doxygen showing the Byte Stream Class Reference. The categories in the list are public member functions, writing (operators for writing to the stream), and reading (operators for reading from the stream)
在空行（空行是段落分隔符）之后是構造函數的實際文檔。用 @param[in/out] 關鍵字標注傳遞給構造函數的參數，Doxygen 基于此生成參數列表：
Screenshot of the Doxygen example showing the parameters under ByteStream
Screenshot of the Doxygen example showing the parameters under ByteStream
值得注意的是 Doxygen 為 buffer() 和 size() 方法自動生成了鏈接。相反，Doxygen 忽略了析構函數前的注釋，因為它并沒有使用特殊注釋：
// Destructor
~ByteStream();現在你已經看到 Doxygen 的絕大部分功能了。通過使用一種稍微改良的注釋格式，讓 Doxygen 能夠識別它們。通過使用一些關鍵字，你甚至可以進一步控制格式化。在下一節中，我會進一步介紹 Doxygen 的其它特性。
其它特性
現在幾乎所有的工作都可以通過對源代碼注釋的方式完成。通過一些微調，你可以輕松地優化 Doxygen 的輸出。
Markdown 格式
為了進階的格式化，Doxygen 支持 Markdown 和 HTML 命令。Markdown 速查表可以在 這里 下載到。
項目主頁
除了自定義頁眉之外，html/index.html 幾乎沒有其它內容了。你可以通過使用關鍵字向其中添加一些有意義的內容。因為主頁通常不是針對某個源代碼文件的，你可以將要顯示在主頁的內容放到項目根目錄下的一個單獨文件中。示例項目中就是這樣做的，其輸出效果如下：
The Doxygen Example Documentation field now contains headings and documentation: Introduction, Running the example, System requirements, and Building the code, with step by step examples and code snippets (all can be found in the example on GitHub)
自動鏈接生成
上面已將提到了，當你引用代碼的其它部分時，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。
