安裝與初始化
請到http://www.stack.nl/~dimitri/doxygen/doxygen_usage.html上面下載最新版本的doxygen。下載針對Windows 95/98/ME/NT/2000/XP Setup版本,只要給予正確的安裝目錄,一步一步的安裝完成。
通過doxywizard裏面的Wizard可以創建新的項目狀態檔案,設置項目名字,項目版本號,源代碼存放的目錄,生成文檔的目錄。
注意:路徑名一定要全英文字,不然識別不了。
通過doxywizard裏面的Expert可以對狀態檔案的Key設置,以下是常用的設置標誌:
PROJECT_NAME |
Project 的名字,以一個單字爲主,多個單字請使用雙引號括住 |
PROJECT_VERSION |
Project的版本號 |
OUTPUT_DIRECTORY |
輸出路徑。產生的文件會放在這個路徑之下。如果沒有填這個路徑,將會以目前所在路徑來作爲輸出路徑。 |
OUTPUT_LANGUAGE |
輸出語言。預設爲English,1.2.16 版後,您可以使用Chinese來輸出中文格式。 |
INPUT |
指定載入或找尋要處理的程序代碼目錄路徑。這個是一個表列式的形態。並且可指定文檔及路徑。舉例來說您有a.c, b.c, c.c 三個文檔。您可使用INPUT = a.c, b.c, c.c 的方式。若您給定一個目錄,該目錄下面所有文檔都會被處理。 |
FILE_PATTERNS |
如果您的INPUT Tag 中指定了目錄。您可以透過這個Tag來要求Doxygen在處理時,只針對特定的文檔進行動作。例如:您希望對目錄下的擴展名爲.c, .cpp及.h的文檔作處理。您可設定FILE_PATTERNS = *.c, *.cpp, *.h。 |
RECURSIVE |
這是一個Bool的Tag,只接受YES或NO。當設定爲YES時,INPUT所指定目錄的所有子目錄都會被處理。 |
EXCLUDE |
如果您有某幾個特定文檔或是目錄,不希望經過Doxygen處理。您可在這個Tag中指定。 |
EXCLUDE_PATTERNS |
類似於FILE_PATTERNS的用法,只是這個Tag是供EXCLUDE所使用。 |
SOURCE_BROWSER |
如果設定爲YES,則Doxygen會產生出原始檔案的列表。 |
INLINE_SOURCES |
如果設定爲YES ,則程序代碼也會被嵌入於說明文件中。 |
ALPHABETICAL_INDEX |
如果設定爲YES,則一個依照字母排序的列表會加入在產生的文件中。 |
GENERATE_HTML |
若設定爲YES ,就會產生HTML版本的說明文件。HTML文件是Doxygen預設產生的格式之一。 |
HTML_OUTPUT |
HTML文件的輸出目錄。這是一個相對路徑,所以實際的路徑爲OUTPUT_DIRECTORY加上HTML_OUTPUT。這個設定預設爲html。 |
HTML_FILE_EXTENSION |
HTML文件的擴展名名。預設爲.html。 |
HTML_HEADER |
要使用在每一頁HTML文件中的Header。如果沒有指定,Doxygen會使用自己預設的Header。 |
HTML_FOOTER |
要使用在每一頁HTML文件中的Footer。如果沒有指定,Doxygen會使用自己預設的Footer。 |
HTML_STYLESHEET |
您可給定一個CSS 的設定,讓HTML的輸出結果更完美。 |
GENERATE_HTMLHELP |
如設定爲YES,Doxygen會產生一個索引檔案。這個索引檔在您需要製作windows 上的HTML格式的HELP檔案時會用的上。 |
GENERATE_TREEVIEW |
若設定爲YES,Doxygen會幫您產生一個樹型結構,在畫面左側。 |
TREEVIEW_WIDTH |
用來設定樹型結構在畫面上的寬寬度。 |
GENERATE_LATEX |
設定爲YES時,會產生LaTeX 的文件。不過您的系統必需要有安裝LaTeX 的相關工具。 |
LATEX_OUTPUT |
LaTeX文件的輸出目錄,與HTML_OUTPUT用法相同,一樣是指在OUTPUT_DIRECTORY之下的路徑。預設爲latex。 |
GENERATE_RTF |
若設定爲YES ,則會產生RTF 格式的說明檔案。 |
RTF_OUTPUT |
與HTML_OUTPUT 用法相同,用來指定RTF 輸出檔案路徑。預設爲rtf。 |
GENERATE_MAN |
若設定爲YES ,則會產生Unix Man Page 格式的說明文件。 |
MAN_OUTPUT |
與HTML_OUTPUT 用法相同,用來指定Man Page的輸出目錄。預設爲man。 |
GENERATE_XML |
若設定爲YES ,則會產生XML 格式的說明文件。 |
ENABLE_PREPROCESSING |
若設定爲YES ,則Doxygen 會啓動C 的前置處理器來處理原始檔案。 |
保存項目狀態,開始生成文檔.
/// Copyright (C), 2005-2007.
/// /file WindowsNT
/// /brief Windows Nice Try.
/// /author Bill Gates
/// /author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// /version 4.0
/// /date 1996-1998
/// /warning This class may explode in your face.
/// /warning If you inherit anything from this class, you're doomed.
/// /ClassList:主要函數列表,每條記錄應包括函數名及功能簡要說明
/// 1. ....
/// /History: 修改歷史記錄列表,每條修改記錄應包括修改日期、修改者及修改內容簡述
////////////////////////////////////////////////////////////////////////////////////
/// Copyright (C), 2005-2007,
/// /file WindowsNT
/// /brief Windows Nice Try.
/// /author Bill Gates
/// /author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// /version 4.0
/// /date 1996-1998
/// /warning This class may explode in your face.
/// /warning If you inherit anything from this class, you're doomed.
/// /Function List:主要函數列表,每條記錄應包括函數名及功能簡要說明
/// 1. ....
/// /History: 修改歷史記錄列表,每條修改記錄應包括修改日期、修改者及修改內容簡述
/// /fn 函數名稱
/// /brief 函數功能、性能等的描述.
/// /param[in] 參數 c a char.
/// /param[out] 參數 n an int.
/// /exception 異常 std::out_of_range parameter is out of range.
/// /return 返回值 a char pointer.
/// /class 類名字 類所在文件 "文件路徑"
/// /brief 大綱描述.
///
/// 詳細描述類的功能
/// A function.
/// A more elaborate description of the constructor.
///< a public variable. Details
標準類型的註釋規範:
Enum
第一種方法
//////////////////////////////////////////////////
/// /enum TEnum
/// A description of the enum type.
//////////////////////////////////////////////////
enum TEnum {
Val1, /// /var Enum Val1
Val2 /// Enum Val2
};
第二種方法
enum在類內部定義
//////////////////////////////////////////////////
/// /enum An enum
/// More detailed enum description..
//////////////////////////////////////////////////
enum TEnum {
TVal1, ///< enum value TVal1.
TVal2, ///< enum value TVal2.
TVal3 ///< enum value TVal3.
}
*enumPtr, ///< enum pointer. Details.
enumVar; ///< enum variable. Details.
#define
macro宏定義//////////////////////////////////////////////////
/// /def MAX(x,y)
/// Computes the maximum of /a x and /a y.
//////////////////////////////////////////////////
//////////////////////////////////////////////////
/// /typedef std::string YString
/// typedef YString.
//////////////////////////////////////////////////
/// /var int g_nCount
/// The description of the int value.
///////////////////////////////////////////////////
您可依照此規定在你自己的程序代碼中加上對應的註釋。其實,無論你有沒有使用Doxygen ,
都不妨按照他的格式將註釋寫入,一方面是依照他的格式,並不會甘於您程序的運行。
另一方面,Doxygen 所定義的都是基本程序註釋應當要的東西。
如果您使用Doxygen Wizard,可直接使用上面的Run 的按鈕或選項來製作說明文件。
如果是生產HTML文件,在HTML_OUTPUT 所指定的目錄中的index.html將是您說明文件的首頁。