文章來自: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生成文檔。主要是兩件事：
- 寫一個配置文件（Doxyfile）。一般用Doxywizard生成后。再手工改動。
- 依照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 須要什么
完畢本文的范例須要下面工具：
- Doxygen的最新版本號。能夠從Doxygen的站點下載。
- Graphviz是一個圖形可視化軟件。Doxygen使用Graphviz生成各種圖形，比如類的繼承關系圖、合作圖，頭文件包括關系圖等。能夠從Graphviz的站點下載Graphviz的最新版本號。Doxygen使用了Graphviz的布局引擎dot，所以在文檔中將其稱作dot。
- 為解決中文問題。須要使用Cygwin的iconv程序作編碼轉換。
- 為解決中文問題，須要一個命令行的查找替換工具。
我選擇了白楊創作的工具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++程序求解“誰養魚”》下載未文檔化的程序。
制作文檔前。我們要完畢下面准備工作：
- 安裝Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help Workshop版本號是4.74.8702.0。英文版。網上有漢化版本號，但執行時會出錯。
- 將iconv和fr程序放到系統路徑包括的文件夾。比如c:\windows\system32。
- 建立一個空文件夾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鍵。再用右鍵點擊文件夾，就會出現“在此處打開命令窗體”的菜單項，選擇就可以。在左側的文件夾樹上。這樣操作無效。