使用doxygen爲C/C++程序生成中文文檔

文章來自:http://www.fmddlmyy.cn/text21.html

依照約定的格式凝視源碼，用工具處理凝視過的源碼產生文檔。經過這樣的方式產生文檔至少有下面優勢：

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

很是多編程語言都有相似的文檔工具，好比：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編譯，中文不能正確顯示。解決問題的思路很是easy：

• 將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命令的朋友應該很是easy看懂這些批處理吧。將這些批處理文件放在工做文件夾（即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...」button，將配置保存在doc\Doxyfile。這時，Doxyfile的內容是Doxygen的默認設置。Doxyfile是普通文本文件。咱們可以直接打開編輯。只是在Doxywizard的界面上填寫也很是方便，每個參數都有具體提示。建議用Doxywizard完畢第一次設置。之後假設需要調整個別參數，可以直接編輯Doxyfile。

3.2 填寫參數

點「Expert...」button後，開始填寫配置參數。

:)，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鍵。再用右鍵點擊文件夾，就會出現「在此處打開命令窗體」的菜單項，選擇就能夠。在左側的文件夾樹上。這樣操做無效。