大家在平時(shí)的編程過(guò)程中,都會(huì)在代碼中插入一些注釋,對(duì)文件,類(lèi),函數(shù),全局變量等進(jìn)行簡(jiǎn)單說(shuō)明.項(xiàng)目完成后,一般也要編寫(xiě)項(xiàng)目的文檔,如何利用源代碼及其中的注釋,自動(dòng)生成圖文并茂的文檔,就是下面要介紹的.

1 工具

    文檔自動(dòng)生成的工具軟件,除了商業(yè)化的如Rational SoDA等,更有開(kāi)源的Doc++和Doxygen等. 本文主要介紹功能全面的Doxygen.
    Doxygen可以對(duì)C++, C, Java, Python等語(yǔ)言進(jìn)行解析并生成HTML,LaTeX,RTF,man page,XML等格式的文檔.

    除了必備的Doxygen (http://www./~dimitri/doxygen/), 如果你還想生成漂亮的類(lèi)圖等,還需要下載graphviz (Doxygen 采用的繪圖工具,http://www./Download..php).


2 Doxygen 的注釋格式

    Doxygen 的注釋格式十分靈活.可以是JavaDoc, Qt和仿c++風(fēng)格, 并且可以混合使用. 如果你熟悉Doc++,就按照你以前的風(fēng)格寫(xiě)好了:). 下面對(duì)每種風(fēng)格簡(jiǎn)單舉例:

-- JavaDoc風(fēng)格:
/**
* your comment text.
*/
-- Qt風(fēng)格:
/*!
* your comment text.
*/
-- 仿c++風(fēng)格:
///                               //!
/// your comment text.      或者: //! your comment text.
///                               //!

    因?yàn)槲乙恢毕矚g用c++的單行注釋風(fēng)格(即'//'),所以下面舉例就以仿c++風(fēng)格為例. 下面注釋中的'@'和'\'等價(jià),可以根據(jù)愛(ài)好選用.
    因?yàn)槭窃陬^文件中定義接口,所以注釋也就主要集中于頭文件中. 如果你想在實(shí)現(xiàn)文件中注釋,其效果和在頭文件中是一樣的.下面就舉一個(gè)實(shí)例.

備注:a) '#' 后面的注釋是我加的簡(jiǎn)單解釋.不屬于文檔注釋內(nèi)容.
     b) Doxygen 允許一條簡(jiǎn)短注釋,加上一條詳細(xì)注釋.其格式也是多樣的. 一般,在 JAVADOC_AUTOBRIEF = NO時(shí),簡(jiǎn)短注釋(///@brief )后空一行,然后再是詳細(xì)注釋. 當(dāng) JAVADOC_AUTOBRIEF = YES時(shí),并且簡(jiǎn)短注釋以第一個(gè)句號(hào)結(jié)束,句號(hào)后跟一空格(即'. ');或者是新起一行,就可以寫(xiě)詳細(xì)注釋了.示例如下:

# 簡(jiǎn)短注釋. 詳細(xì)注釋.
/// Brief description which ends at this dot. Details follow
/// here.

    c) 如果同一代碼條目在聲明和定義處都有簡(jiǎn)短注釋和詳細(xì)注釋, 則文檔只采用聲明前的簡(jiǎn)短注釋和定義前的詳細(xì)注釋.
    d) 如果是在行尾注釋變量,參數(shù)等,在你選用的注釋格式后面加上'<', 如: ///<行尾的注釋.


----------------------------- Example Begin ---------------------------------
# 文件的注釋格式
# 注釋文件,格式: ///@file 文件名 文件的簡(jiǎn)短注釋.
///@file socket_c.h head file of class socket_c.
# 文件的詳細(xì)注釋.
///Define the interface of class socket_c.
# 普通注釋,不會(huì)生成在文檔中.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $

# 類(lèi)的注釋,格式: ///@brief 簡(jiǎn)短注釋內(nèi)容.
///@brief class of server socket.
class socket_c
{
private:

public:
    # 函數(shù)的注釋格式
    # 函數(shù)的注釋,格式: ///@brief 函數(shù)的簡(jiǎn)短注釋.
    ///@brief handle the connections of clients.
    # 參數(shù)注釋,格式: ///@param 參數(shù)的簡(jiǎn)短注釋.
    ///@param server the server ip address.
    ///@param serv_port the server #port.
    # 返回值注釋,格式: ///@return 返回值的簡(jiǎn)短注釋.
    ///@return connected socketfd.
    # 具體返回值的注釋,格式: ///@retval 返回值 該返回值的注釋.
    ///@retval connfd on success.
    ///@retval 0 on EINTR - system call.
    ///@retval -1 on error.
    # 參見(jiàn)...,格式: ///@see 參見(jiàn)的類(lèi)/文件等.
    ///@see main_ppc.cpp
    int accept_client(const int listenfd);
};

# 自定義類(lèi)型的注釋
///@brief structure of child process.
struct child_proc_s
{
    # 行尾的注釋,格式: ///< 注釋內(nèi)容.
    pid_t child_pid;    ///<child process id.
    int child_pipefd;    ///<parent's stream pipe to/from child.
};

# 全局變量的注釋,也可以采用上面的行尾格式進(jìn)行注釋.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------


3 配置文件的生成與修改

    Doxygen的功能強(qiáng)大,配置選項(xiàng)也十分多. 如果是命令行模式, 有些不便. 因此建議使用GUI的Doxywizard(可以從<開(kāi)始>菜單中運(yùn)行). 下面就對(duì)我個(gè)人認(rèn)為比較重要的選項(xiàng),并結(jié)合實(shí)例 (生成html文檔) 進(jìn)行簡(jiǎn)單說(shuō)明.
    下面列出的一般是需要修改的,未列出的我采用缺省值.

# Project選項(xiàng)
#---------------------------------------------------------------------------
# Staff_TPC是生成文檔的項(xiàng)目名,會(huì)顯示在文檔中.
PROJECT_NAME           = Staff_TPC
PROJECT_NUMBER         = 1.0    # 項(xiàng)目版本號(hào)
# 生成文檔的輸出路徑
OUTPUT_DIRECTORY       = "f:/My Documents/cpp/horin/staff/"
# 生成文檔的語(yǔ)言,缺省是English,也可以是簡(jiǎn)體中文等.
OUTPUT_LANGUAGE        = English
JAVADOC_AUTOBRIEF      = YES    # 打開(kāi)此選項(xiàng).

# Build 選項(xiàng)
#---------------------------------------------------------------------------
SHOW_INCLUDE_FILES     = NO        # 不顯示所有包括的文件.

# input 選項(xiàng)
#---------------------------------------------------------------------------
# 要生成文檔的源文件的路徑. 如果是一個(gè)目錄,則是該目錄下的所有文件; 當(dāng)然,也可以
# 是具體的某個(gè)文件.
INPUT                  = "f:/My Documents/cpp/horin/staff/tpc/"
# 輸入文件的匹配模式,下面是c / c++語(yǔ)言的設(shè)置.
FILE_PATTERNS          = *.c \
                         *.cpp \
                         *.h \
                         *.hpp
RECURSIVE              = YES    # 需要遞歸處理子目錄.

# source browser選項(xiàng)
#---------------------------------------------------------------------------
# 如為SOURCE_BROWSER和INLINE_SOURCES都設(shè)置為YES, 則生成的文檔中會(huì)包括源代碼
# (即.cpp文件),這可以方便閱讀時(shí)查看源代碼.
SOURCE_BROWSER         = NO
INLINE_SOURCES         = NO
STRIP_CODE_COMMENTS    = YES    # 忽略普通的文檔注釋.
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
VERBATIM_HEADERS       = YES

# HTML 選項(xiàng)
#---------------------------------------------------------------------------
GENERATE_HTML          = YES    # 需要生成html格式的文檔.
GENERATE_HTMLHELP      = YES    # 需要生成windows HTMLHELP格式的目錄,以方便閱讀.
GENERATE_TREEVIEW      = YES    # 需要生成樹(shù)視圖,以方便閱讀.

# LaTeX 選項(xiàng)
#---------------------------------------------------------------------------
GENERATE_LATEX         = NO        # 不需要生成LaTeX輸出.

# dot 選項(xiàng) # 此選項(xiàng)是生成圖形,建議(需要)安裝graphviz.
#---------------------------------------------------------------------------
CLASS_DIAGRAMS         = YES
HIDE_UNDOC_RELATIONS   = YES
HAVE_DOT               = YES    # 已經(jīng)安裝graphviz.打開(kāi)此選項(xiàng).
CLASS_GRAPH            = YES    # 生成類(lèi)圖
COLLABORATION_GRAPH    = YES    # 生成協(xié)作圖
UML_LOOK               = NO

    在上面根據(jù)自己的需要對(duì)各個(gè)選項(xiàng)進(jìn)行了配置,下面很重要的一步,就是把配置保存下來(lái). 呵呵,這是大家最擅長(zhǎng)的了. 可以命名配置文件為Doxygen-YourName.txt, 今后只需修改project和input選項(xiàng),即可重用.


4 文檔的生成

    在Doxywizard中打開(kāi)上面的配置文件Doxygen-YourName.txt, 根據(jù)需要修改project和input選項(xiàng)(也可以在文本編輯器中直接修改Doxygen-YourName.txt), 點(diǎn)擊菜單Doxygen->Run(ctrl+r),稍微休息一會(huì),你就可以看到在OUTPUT_DIRECTORY路徑下生成了一個(gè)html的子目錄.該子目錄下就是你需要的文檔. 運(yùn)行index.html文件, 是否見(jiàn)到了你想要的.很有可能,還見(jiàn)到了你意想不到的.


5 Doxygen的其他用途

    Doxygen配合graphviz, 可以生成UML設(shè)計(jì)圖形,如類(lèi)圖,協(xié)作圖. 如你拿到一份源代碼,因?yàn)轭?lèi)的關(guān)系復(fù)雜,或者沒(méi)有文檔, 此時(shí)你就可以利用Doxygen來(lái)進(jìn)行簡(jiǎn)單的反向工程了.