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

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

安装与初始化

    请到上面下载最新版本的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: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述

///                

///      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: 修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述

///                

///      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將是您说明文件的首页。