使用doxygen為C/C++程式產生中文文檔（上）

使用doxygen為C/C++程式產生中文文檔（上）

按照約定的格式注釋原始碼，用工具處理注釋過的原始碼產生文檔。通過這種方式產生文檔至少有以下好處：

• 便於代碼和文檔保持同步。
• 可以對文檔做版本管理。

很多程式設計語言都有類似的文檔工具，例如：Java有javadoc，Ruby有rdoc。對於C/C++程式，我們可以用Doxygen產生文檔。本文通過為一個C++程式“誰養魚”建立文檔，介紹了怎樣在Windows平台使用Doxygen。

Doxygen比較適合製作API的介面文檔，CHM是這類文檔的常見格式。最新版本的Doxygen（目前是1.5.2）統一採用UTF-8作為輸出檔案的編碼格式，但微軟的CHM編譯工具不支援UTF-8，這就為製作中文CHM文檔帶來麻煩。本文提出瞭解決這個問題的方法。

1 Doxygen簡介1.1 要做什麼

使用Doxygen產生文檔，主要是兩件事：

1. 寫一個設定檔（Doxyfile）。一般用Doxywizard產生後，再手工修改。
2. 按照Doxygen的約定，將代碼“文檔化”。

然後只要執行命令：

doxygen Doxyfile

就可以了。輸入檔案、輸出目錄、參數等都是在Doxyfile中配置的。

1.2 得到什麼

Doxygen的輸出格式主要有HTML、LATEX、RTF等：

• Doxygen在輸出HTML文檔時，可以自動準備用於製作CHM的專案檔（.hhp）、目錄檔案（.hhc）和索引檔案（.hhk）。用HTML Help Workshop中的CHM編譯器（hhc.exe）編譯後產生CHM檔案。
• Doxygen在輸出LATEX文檔的同時準備了轉換到pdf格式的makefile。只要系統安裝了合適的TEX工具，就可以從LATEX文檔產生pdf文檔。
• Doxygen輸出的RTF格式，已經針對Word作了最佳化，可以較好地轉換到Word文檔。

1.3 需要什麼

完成本文的範例需要以下工具：

1. Doxygen的最新版本，可以從Doxygen的網站下載。
2. Graphviz是一個圖形可視化軟體。Doxygen使用Graphviz產生各種圖形，例如類的繼承關係圖、合作圖，標頭檔內含項目關聯性圖等。可以從Graphviz的網站下載Graphviz的最新版本。Doxygen使用了Graphviz的布局引擎dot，所以在文檔中將其稱作dot。
3. 為解決中文問題，需要使用Cygwin的iconv程式作編碼轉換。
4. 為解決中文問題，需要一個命令列的尋找替換工具。我選擇了白楊創作的工具fr。

可以從我的首頁http://www.fmddlmyy.cn下載這些工具：Doxygen 1.5.2、Graphviz 2.12、iconv (GNU libiconv 1.9)和fr 2.1.1.120。

2 CHM格式的中文問題

前面說過：目前，Doxygen統一採用UTF-8作為輸出檔案的編碼格式，但微軟的CHM編譯工具（hhc.exe）不支援UTF-8。如果直接用hhc.exe編譯，中文不能正確顯示。解決這個問題的思路很簡單：

• 將Doxygen輸出的html檔案以及CHM的專案檔（.hhp）、目錄檔案（.hhc）和索引檔案（.hhk）全部轉換到GBK編碼後，再用hhc.exe編譯即可。

可以用iconv對檔案作編碼轉換。對於html檔案，除了檔案內容的編碼轉換外，還要將

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

中的“UTF-8”替換成“gb2312”。

2.1 用批處理簡化操作

我寫了一些批次檔（.bat）用於簡化處理過程，包括：

2.1.1 clean.bat —— 清空以前輸出

@echo off
echo 清空以前輸出
if exist refman.chm del /f /q refman.chm
if exist output/html del /f /q output/html/*.*
if exist output/latex del /f /q output/latex/*.*
if exist output/rtf del /f /q output/rtf/*.*
if exist output del /f /q output/*.*


2.1.2 build.bat —— 調用doxygen產生文檔

@echo off
echo 產生文檔
doxygen Doxyfile


2.1.3 utf82gbk.bat —— 將指定檔案（支援萬用字元）從utf-8編碼轉換到gbk編碼

@echo off
echo 將%1從utf-8編碼轉換到gbk編碼
for %%f in (%1) do copy %%f %%f.utf8
for %%f in (%1) do iconv -c -f utf-8 -t gbk %%f.utf8 > %%f


這個批次檔要求系統當前路徑上有iconv.exe。執行iconv時，使用-c參數忽略無法轉換的字元。否則如果輸入檔案包含無法轉換的字元，轉換會失敗。輸入檔案被備份到加過.utf8尾碼的檔案。

2.1.4 html-utf82gbk.bat —— 將指定html檔案（支援萬用字元）從utf-8編碼轉換到gbk編碼

@echo off
call utf82gbk %1
echo 將%1中的charset從UTF-8改為gb2312
fr %1 -f:charset=UTF-8 -t:charset=gb2312


這個批次檔要求系統當前路徑上有iconv.exe和白楊的fr.exe。

2.1.5 makechm.bat —— 用Doxygen的輸出製作chm檔案

@echo off
echo 將Doxygen輸出檔案編碼從utf-8轉換到gbk
set path=%path%;%cd%
cd output/html

echo 處理chm輸入檔案
call utf82gbk.bat index.hhp
call utf82gbk.bat index.hhc
call utf82gbk.bat index.hhk
call html-utf82gbk *.html

echo 產生chm檔案
"C:/Program Files/HTML Help Workshop/hhc.exe" index.hhp

if exist index.chm copy index.chm ../../refman.chm
del /f /q *.chm
cd ../..


這個批次檔假設系統在目錄“C:/Program Files/HTML Help Workshop/”安裝了“HTML Help Workshop”。並假設輸出目錄是Doxyfile所在目錄的子目錄output。

2.1.6 rebuild.bat —— 重建chm檔案

@echo off
call clean.bat
call build.bat
call makechm.bat


2.2 小結

瞭解DOS命令的朋友應該很容易看懂這些批處理吧。將這些批次檔放在工作目錄（即Doxyfile所在目錄）後，每次只要鍵入rebuild就可以重建chm檔案。必要時可以單獨使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也可以單獨使用。讀者可以從我的首頁www.fmddlmyy.cn下載這些批次檔。

3 建立設定檔3.1 準備工作

“誰養魚”是我最近寫的一個小程式，它用推理法求解愛因斯坦謎題——“誰養魚”。讀者可從《窮舉和推理：用C++程式求解“誰養魚”》下載未文檔化的程式。

製作文檔前，我們要完成以下準備工作：

1. 安裝Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help Workshop版本是4.74.8702.0，英文版。網上有漢化版本，但運行時會出錯。
2. 將iconv和fr程式放到系統路徑包含的目錄，例如c:/windows/system32。
3. 建立一個空目錄fish，放入要注釋的程式（fish/src），建立製作文檔的工作目錄（fish/doc），將前面介紹的批次檔放到doc目錄。

好了，現在可以運行Doxywizard建立設定檔。

可以直接點“Save...”按鈕，將配置儲存在doc/Doxyfile。這時，Doxyfile的內容是Doxygen的預設設定。Doxyfile是普通文字檔，我們可以直接開啟編輯。不過在Doxywizard的介面上填寫也很方便，每個參數都有詳細提示。建議用Doxywizard完成第一次設定。以後如果需要調整個別參數，可以直接編輯Doxyfile。

3.2 填寫參數

點“Expert...”按鈕後，開始填寫配置參數。

:)，Doxygen是不是有很多參數？其實大多數參數都有預設值，需要填寫的不算多，下面分頁介紹：

3.2.1 Project頁

DOXYFILE_ENCODING是Doxyfile的文本編碼。如果檔案中有中文字元，可以填寫GBK。

填寫項目名（PROJECT_NAME）、項目版本（PROJECT_NUMBER）、輸出目錄（OUTPUT_DIRECTORY）和輸出語言（OUTPUT_LANGUAGE）。輸出目錄可以按Doxyfile的相對目錄填寫。輸出語言相當於程式資源，選擇Chinese。

Doxywizard的中文支援不完善，中文字元會被存為亂碼。我們直接編輯Doxyfile，填寫：

PROJECT_NAME = 誰養魚

取消FULL_PATH_NAMES。我們修改了以下參數：

DOXYFILE_ENCODING	GBK
PROJECT_NAME	誰養魚
PROJECT_NUMBER	1.0
OUTPUT_DIRECTORY	output
OUTPUT_LANGUAGE	Chinese
FULL_PATH_NAMES	NO

3.2.2 Messages頁

在Messages頁將WARN_LOGFILE填寫為build.log。這樣，Doxygen會將編譯時間出現的警告和錯誤儲存在build.log，我們可以對照修改。

WARN_LOGFILE

build.log

3.2.3 Input頁

指定輸入源檔案目錄（INPUT），將輸入檔案編碼（INPUT_ENCODING）改為GBK。

INPUT	../src
INPUT_ENCODING	GBK

FILE_PATTERNS參數是Doxygen要處理的檔案類型，預設值包括Doxygen支援的所有檔案類型。不能用Doxygen文檔化任意檔案類型。例如Doxygen不支援組譯工具。

3.2.4 Source Browser頁

選擇SOURCE_BROWSER，在文檔中包含原始碼。

SOURCE_BROWSER

YES

3.2.5 Html頁

選擇GENERATE_HTMLHELP後，Doxygen會準備產生chm檔案需要的專案檔、目錄檔案和索引檔案。可以通過參數HTML_HEADER和HTML_FOOTER定製頁面，參數值是包含定製內容的檔案名稱。例如，我們可以建立檔案html_foot，內容為：

<p align="right"><A HREF="http://www.fmddlmyy.cn/text20.html" target="_top">窮舉和推理：用C++程式求解“誰養魚”</A></p>
</BODY>
</HTML>

然後將HTML_FOOTER的值設為html_foot。

GENERATE_HTMLHELP	YES
HTML_FOOTER	html_foot

3.2.6 LaTex頁

取消GENERATE_LATEX，不產生LaTex輸出。

GENERATE_LATEX

NO

3.2.7 Dot頁

在Dot頁，可以選上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函數調用其它函數的，例如：

CALLER_GRAPH是本函數調用者的，例如：

UML_LOOK	YES
CALL_GRAPH	YES
CALLER_GRAPH	YES

3.3 運行Doxygen

對於“誰養魚”這個例子，其它參數都可以使用預設值。從命令列進入doc目錄後（參見附錄1）運行rebuild.bat，就可以產生refman.chm。這時，我們還沒有對程式作任何文檔化，輸出僅包含Doxygen通過Dot產生的。

我們可以編輯Doxyfile，將EXTRACT_ALL設為YES，再rebuild。這時，Doxygen會自動提取程式的所有要素，包括檔案、函數、變數、類型定義、枚舉、枚舉值、宏定義等。

只想看看結果的朋友可以下載這個chm檔案。Doxygen設定檔中所有參數的詳細參考可以查閱Doxygen手冊中的“Configuration”頁。上篇到此結束。下篇將介紹文檔化程式的方法。

後記（2007/7/15）

不少朋友說按照我的說明不能產生期待的結果，這一定是我的文章表述不清了，不好意思。最近，我手頭事情比較多，這幾個月恐怕沒時間寫本文的下篇了。好在網上介紹Doxygen文檔化的文章還是不少的，少我這篇應該也沒什麼。

其實，這篇文章的目的只是讓不熟悉doxygen的朋友能夠快速地瞭解這個工具。大家如果真的要使用doxygen，還是應該多花些時間看看它的文檔。我把本文範例的工作目錄打包放在我的首頁www.fmddlmyy.cn上，需要的朋友可以下載。這是個未完成的版本，我去掉了EXTRACT_ALL，注釋了幾個函數。因為注釋不完整，編譯（在doc目錄rebuild）時還會產生非空的build.log。log是善意的提示，可以協助我們完善文檔。

附錄1 快速進入命令列並轉到指定目錄

如果經常用到命令列，可以在註冊表的“HKEY_CLASSES_ROOT/Folder/shell”下建立“Command Prompt Here”項及其子項“command”，將“command”項的預設值設為字串值“cmd.exe”。這時，只要在資源管理員的任意目錄上點擊右鍵並選擇“Command Prompt Here”就可以快速進入命令列並轉到指定目錄。

我將這個登錄機碼儲存成reg檔案：

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT/Folder/shell/Command Prompt Here]

[HKEY_CLASSES_ROOT/Folder/shell/Command Prompt Here/command]
@="cmd.exe"

需要的朋友可以下載後雙擊匯入註冊表即可。

在vista上，這樣操作不能進入指定目錄，也沒有必要這樣做。在vista中：只要在資源管理員中先按下shift鍵，再用右鍵點擊檔案夾，就會出現“在此處開啟命令視窗”的功能表項目，選擇即可。在左側的分類樹上，這樣操作無效。