Doxygen代码注释规定和生产文档说明

http://blog.chinaunix.net/uid-20372841-id-1695818.html

Doxygen是一个程序的文档产生工具，可将程序中的特点注释转换成为说明文件。

安装与初始化

请到http://www.stack.nl/~dimitri/doxygen/doxygen_usage.html上面下载最新版本的doxygen。下载针对Windows 95/98/ME/NT/2000/XP Setup版本，只要给予正确的安装目录，一步一步的安装完成。

Doxygen产生文档分为三个步骤：
a． 为Project建立项目档案；
b． 在程序代码中加上符合Doxygen所定义的注释格式；
c． 使用Doxygen来产生文档；


为你的Project制作Doxygen的项目状态档案，这个所谓项目项目状态档案，格式其实是一些Key与值的设定。
通过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: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述
/// <author> <time> <version > <desc>
/// Hsz 2005/4/12 1.0 build this moudle
////////////////////////////////////////////////////////////////////////////////////

源文件头部注释规范，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内：
/////////////////////////////////////////////////////////////////////////////////
/// 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: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述
/// <author> <time> <version > <desc>
/// Hsz 2005/4/12 1.0 build this moudle
/////////////////////////////////////////////////////////////////////////////////




函数头部注释规范，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内：
/////////////////////////////////////////////////////////////////////////////////
/// \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类型定义
//////////////////////////////////////////////////
/// \typedef std::string YString
/// typedef YString.
//////////////////////////////////////////////////

Struct结构
//////////////////////////////////////////////////
/// \struct Test struct.h "inc/ struct.h"
/// \brief This is a test struct.
/// Some details about the Test struct
///////////////////////////////////////////////////

变量定义
///////////////////////////////////////////////////
/// \var int g_nCount
/// The description of the int value.
///////////////////////////////////////////////////
您可依照此规定在你自己的程序代码中加上对应的注释。其实，无论你有没有使用Doxygen ，
都不妨按照他的格式將注释写入，一方面是依照他的格式，並不会甘于您程序的运行。
另一方面，Doxygen 所定义的都是基本程序注释应当要的东西。
如果您使用Doxygen Wizard，可直接使用上面的Run 的按鈕或选项來制作说明文件。
如果是生产HTML文件，在HTML_OUTPUT 所指定的目录中的index.html將是您说明文件的首页。