用doxygen為C/C++程式自動產生文檔（一）

用doxygen為C/C++程式自動產生文檔（一）

轉載請註明：嵌入式學習網 www.embstudy.org

這幾天有人問起關於文檔產生工具的問題，個人覺得 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環境變數指定的目錄下，解決辦法：

mkdir qt         cd qt         ln -s your-qt-include-dir-here include         ln -s your-qt-lib-dir-here lib        export QTDIR=$PWD

2.         Bison 問題

a)         Bison 1.31至1.34版本有一個Bug，可以使用1.35或1.31以前的版本