用doxygen爲C/C++程序自動生成文檔（一），簡介及安裝
用doxygen爲C/C++程序自動生成文檔（一）
轉載請註明：http://blog.mcuol.com/User/fenghua/Article/17348_1.htm
這幾天有人問起關於文檔生成工具的問題，個人覺得 doxygen 是一個不錯的由C/C++ 註釋自動生成文檔的工具軟件。在這裏簡單說明一下 doxygen 的使用，供大家參考。
一、doxygen 簡介
二、簡單說，doxygen 就是一個文檔系統，它可以爲C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D 等語言生成文檔。
官方網站：http://www.stack.nl/~dimitri/doxygen/index.html
它可以從三個方面幫助我們：
1、 它可以產生HTML格式的在線文檔或LATEX格式的離線參考手冊，另外它還可以生成RTF（MS-WORD）, PostScript, 帶超鏈接的PDF，壓縮的HTML，unix man 等格式的文檔。這些文檔是直接從源文件提取的，這有助於保持代碼和文檔的一致性。
a) Doxygen在輸出HTML文檔時，自動生成用於製作CHM的項目文件（.hhp）、目錄文件（.hhc）和索引文件（.hhk）。可以使用HTML Help Workshop中的CHM編譯器（hhc.exe）編譯後生成CHM文件。
b) Doxygen輸出LATEX文檔的同時，生成了了轉換成pdf格式的文件的makefile。只要系統安裝了相應的TEX工具，就可以從LATEX文檔生成pdf文檔。
c) Doxygen輸出的RTF格式，針對Word作了優化，可以很好的轉換到Word文檔。
2、 通過配置 doxygen，可以從非文檔化的源文件中提取源文件結構，這有助於幫我們理清大的源碼包的結構。它能夠自動的產生包括：依賴圖，繼承圖，協作圖等元素之間關係的圖表（需要graphviz支持）。
a) Graphviz是一個圖形化軟件，Doxygen使用Graphviz生成各種圖形。
b) Graphviz下載地址 http://www.graphviz.org/Download..php
3、 甚至可以“濫用”來創建普通文檔。
http://www.graphviz.org/Download..php
三、Doxygen協議
Doxygen是在GPL協議下發布的，你可以使用其源碼或編譯好的二進制文件。Doxygen幾乎可以在所有的linux兼容系統上運行，它也可以運行在windows環境。你可以根據需要選擇。
四、 Doxygen的文檔、FAQ、使用者和相關文章
a) http://www.stack.nl/~dimitri/doxygen/manual.html
b) http://www.stack.nl/~dimitri/doxygen/faq.html
c) http://www.stack.nl/~dimitri/doxygen/projects.html
d) http://www.stack.nl/~dimitri/doxygen/articles.html
五、使用Doxygen的一般步驟
a) 下載 Doxygen軟件 http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
b) 下載 Graphviz http://www.graphviz.org/Download..php
c) 安裝 Doxygen 和 Graphviz（可選）
d) 準備一個配置文件（Doxyfile），通常用Doxywizard生成，然後可以根據需要修改（也可以不改）。
e) 按照Doxygen規則給源代碼添加註釋，將代碼文檔化
f) 運行Doxygen 產生和源代碼對應的文檔。
六、安裝doxygen
a) Win下的安裝
i. 直接運行Doxygen 的 Setup EXE文件，安裝提示操作就可以了
ii. 運行Graphviz的安裝（EXE）文件，按提示操作即可（可選）
b) 在unix兼容系統上採用編譯源碼方式安裝 Doxygen
i. 採用源碼安裝 Doxygen 要確認你的系統安裝有：
1. flex, bison 和 make等GNU工具
2. Perl
3. configure 腳步要求你的系統上有標準Unix命令如：sed, date, find, uname, mv, cp, cat, echo, tr, cd, and rm等
4. 爲了使用Doxygen的高級功能，還需要安裝以下附件工具
a) Qt3.3或更高版本，doxygen用其構建GUI前端doxywizard
b) 一個Latex軟件：如teTeX 1.0，用來產生LaTex、Postscript和PDF格式的輸出。
c) Graph visualization toolkit 1.8.10或更高版本。Doxygen用它生成包含圖、依賴圖、繼承圖和協作圖等。如果採用編譯源碼方式安裝graphviz，你的系統需要freetype支持。
d) 如果需要公式，或者你不希望使用pdflatex，則需要ghostscript，這個軟件可以在www.ghostscript.com上找到
e) 爲了產生Doxygen自己格式的文檔，Python也是需要的，www.python.org.
ii. 解壓下載的Doxygen源碼包
1. tar xf doxygen-$VERSION.src.tar
2. ./configure 會根據系統自動配置doxygen，併產生相應的makefile
a) 可以configure --platform platform-type自定平臺類型
b) configure --with-doxywizard 可以圖形前端doxywizard
c) 更多信息可以通過configure –help查看，並給定相應的配置
iii. 編譯Doxygen
1. make
iv. 可選的產生手冊
1. make docs
2. make pdf
v. 安裝 Doxygen
1. make install （需要root用戶權限）
vi. 已知的問題
1. 有些系統中，QT頭文件和庫文件不在QTDIR環境變量指定的目錄下，解決辦法：
2. Bison 問題
a) Bison 1.31至1.34版本有一個Bug，可以使用1.35或1.31以前的版本
3. Latex問題
4. 文件 a4wide.sty 不是在所有的版本中都有效的，如果你使用的版本不支持請在config文件中選擇其他的 pager type，具體可以參看 PAPER_TYPE 相關幫助
vii.
c) Ubuntu下采用二進制文件安裝,可以用root用戶使用下面的指令安裝：
i. apt-get install doxygen doxygen-doc doxygen-gui graphivz
d) 其他安裝細節請參考 http://www.stack.nl/~dimitri/doxygen/install.html
春節後在陸續整理使用和其他相關問題。