C++ 程序文档生成器介绍(doxygen)

程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。

好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。
本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：

C++ 程序文档生成器介绍(doxygen)     沐枫网志

1. 模块定义（单独显示一页）

/** @defgroup 模块名 模块的说明文字

 *  @{

 */

 

 ... 定义的内容 ...

 

/** @} */ // 模块结尾

 

2. 分组定义（在一页内分组显示）

/** @name 分组说明文字

 *  @{

 */

 

 ... 定义的内容 ...

 

/** @} */

 

3. 变量、宏定义、类型定义简要说明

/** 简要说明文字 */

#define FLOAT float

 

/** @brief 简要说明文字（在前面加 @brief 是标准格式） */

#define MIN_UINT 0

 

/** 分行的简要说明 /n

 *  这是第二行的简要说明

 */

int b;

 

4. 函数说明

/** 简要的函数说明文字 

 *  @param [in] param1 参数1说明

 *  @param [out] param2 参数2说明

 *  @return 返回值说明

 */

int func(int param1, int param2);

 

/** 打开文件 /n

 *  文件打开成功后，必须使用 ::CloseFile 函数关闭。

 *  @param[in] file_name 文件名字符串

 *  @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：

 *  - r 读取

 *  - w 可写

 *  - a 添加

 *  - t 文本模式(不能与 b 联用)

 *  - b 二进制模式(不能与 t 联用)

 *  @return 返回文件编号

 *  - -1 表示打开文件失败

 

 *  @note 文件打开成功后，必须使用 ::CloseFile 函数关闭

 *  @par 示例:

 *  @code

    // 用文本只读方式打开文件

    int f = OpenFile("d://test.txt", "rt");

 *  @endcode

 

 *  @see ::ReadFile ::WriteFile ::CloseFile

 *  @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。

 */

int OpenFile(const char* file_name, const char* file_mode);

 

5. 枚举类型定义

/** 枚举常量 */

typedef enum TDayOfWeek

{

SUN = 0,  /**<  星期天（注意，要以 “<” 小于号开头） */

MON = 1,  /**<  星期一 */

TUE = 2,  /**<  星期二 */

WED = 3,  /**<  星期三 */

THU = 4,  /**<  星期四 */

FRI = 5,  /**<  星期五 */

SAT = 6   /**<  星期六 */

}

/** 定义类型 TEnumDayOfWeek */

TEnumDayOfWeek;  

　　

6. 项目符号标记

  /** 
   *  A list of events:
   *    - mouse events
   *         -# mouse move event
   *         -# mouse click event/n
   *            More info about the click event.
   *         -# mouse double click event
   *    - keyboard events
   *         -# key down event
   *         -# key up event
   *
   *  More text here.
   */

 

结果为：

A list of events:

• mouse events
  1. mouse move event
  2. mouse click event
     More info about the click event.
  3. mouse double click event
• keyboard events
  1. key down event
  2. key up event

More text here.

代码示范：

/**/ /** @defgroup EXAMPLES 自动注释文档范例
 *  @author  林勇
 *  @version 1.0
 *  @date    2004-2005
 *  @{
 */


/**/ /** @name 文件名常量
 *  @{
 */

/**/ /** 日志文件名 */
#define  LOG_FILENAME "d://log//debug.log"
/**/ /** 数据文件名 */
#define  DATA_FILENAME "d://data//detail.dat"
/**/ /** 存档文件名 */
#define  BAK_FILENAME "d://data//backup.dat"

/**/ /** @}*/   //  文件名常量

/**/ /** @name 系统状态常量
 *  @{
 */
 
/**/ /** 正常状态 */
#define  SYS_NORMAL 0
/**/ /** 故障状态 */
#define  SYS_FAULT 1
/**/ /** 警告状态 */
#define  SYS_WARNNING 2

/**/ /** @}*/   //  系统状态常量



/**/ /** 枚举常量 */
typedef  enum  TDayOfWeek
{
        SUN = 0, /**//**< 星期天 */
        MON = 1, /**//**< 星期一 */
        TUE = 2, /**//**< 星期二 */
        WED = 3, /**//**< 星期三 */
        THU = 4, /**//**< 星期四 */
        FRI = 5, /**//**< 星期五 */
        SAT = 6  /**//**< 星期六 */
}
/**/ /** 定义类型 TEnumDayOfWeek */
TEnumDayOfWeek;  
/**/ /** 定义类型 PEnumDayOfWeek */
typedef TEnumDayOfWeek *  PEnumDayOfWeek; 

/**/ /** 定义枚举变量 enum1 */
TEnumDayOfWeek enum1;        
/**/ /** 定义枚举指针变量 enum2 */
PEnumDayOfWeek p_enum2; 



/**/ /** @defgroup FileUtils 文件操作函数
 *  @{
 */

/**/ /** 打开文件 /n
 *  文件打开成功后，必须使用 ::CloseFile 函数关闭。
 *  @param[in] file_name 文件名字符串
 *  @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：
 *  - r 读取
 *  - w 可写
 *  - a 添加
 *  - t 文本模式(不能与 b 联用)
 *  - b 二进制模式(不能与 t 联用)
 *  @return 返回文件编号
 *  - -1 表示打开文件失败
 
 *  @note 文件打开成功后，必须使用 ::CloseFile 函数关闭
 *  @par 示例:
 *  @code
    // 用文本只读方式打开文件
    int f = OpenFile("d://test.txt", "rt");
 *  @endcode
 
 *  @see ::ReadFile ::WriteFile ::CloseFile
 *  @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
 */
int  OpenFile( const   char *  file_name,  const   char *  file_mode);

/**/ /** 读取文件 
 *  @param[in] file 文件编号，参见：::OpenFile
 *  @param[out] buffer 用于存放读取的文件内容
 *  @param[in] len 需要读取的文件长度
 *  @return 返回读取文件的长度
 *  - -1 表示读取文件失败
 
 *  @pre /e file 变量必须使用 ::OpenFile 返回值
 *  @pre /e buffer 不能为 NULL
 *  @see ::OpenFile ::WriteFile ::CloseFile
 */
int  ReadFile( int  file,  char *  buffer,  int  len);

/**/ /** 写入文件 
 *  @param[in] file 文件编号，参见：::OpenFile
 *  @param[in] buffer 用于存放将要写入的文件内容
 *  @param[in] len 需要写入的文件长度
 *  @return 返回写入的长度
 *  - -1 表示写入文件失败
 
 *  @pre /e file 变量必须使用 ::OpenFile 返回值
 *  @see ::OpenFile ::ReadFile ::CloseFile
 */
int  WriteFile( int  file,  const   char *  buffer,  int  len);

/**/ /** 关闭文件 
 *  @param file 文件编号，参见：::OpenFile
 *  @retval 0  为成功
 *  @retval -1 表示失败
 
 *  @see ::OpenFile ::WriteFile ::ReadFile
 *  @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
 */
int  CloseFile( int  file);

/**/ /** @}*/   //  文件操作函数

/**/ /** @}*/   //  自动注释文档范例





今天下午看了看Doxygen的文档，把一些自己认为比较常用的TAG注解了一下，本想全部翻译的，可是后来看了一遍之后，就懒了，太多了，嘿嘿，就做个摘要算了吧。嘿嘿

<> 里面的是必须的，{}表示可选的:

@a　<word>　用斜体显示后面跟随的一个词
@anchor <word>　标记锚点
@arg　{ item-description }　@arg @c 参数的描述
@attention  { attention text }　标记需要注意的段落
@author { list of authors }　作者
@b <word> 用粗体显示后面跟随的一个词
@brief {brief description} 概要
@bug { bug description } 臭虫
@c <word> 打字机字体
@class <name> [<header-file>] [<header-name>] 类
@date { date description } 日期
@def <name> 宏描述
@deprecated { description } 废弃的
@e <word> 斜体字
@em <word> 斜体字
@enum <name> 描述enum,比如:
/*! @enum Test::TEnum
 * A description of the enum type.
 */
@example <file-name> 例子文件
@exception  <exception-object> { exception description }异常描述
@f$  公式
@f[  公式
@f]  公式
@file [<name>] 文件说明
@fn (function declaration) 函数说明
@htmlonly 后面的东西原封不动的插入生成的html当中,直到遇到 @endhtmlonly
@image <format> <file> ["caption"] [<sizeindication>=<size>] 插入图像文件
@interface <name> [<header-file>] [<header-name>] 描述接口和@class同意
@link <link-object> 插入链接
@n 强制新行
@namespace <name> 名字空间
@note { text }  注解
@overload [(function declaration)] 重载
@p 打字机字体
@property  属性说明
@ref <name> ["(text)"] 引用锚点
@remarks { remark text } 备注
@return 返回值
@retval 返回值列表
@sa =@see 参见
@section  段落
@see   参见
@struct  结构
@test { paragraph describing a test case }
@throw = @exeception
@todo { paragraph describing what is to be done } 要完成的任务
@typedef
@union
@var (variable declaration) 变量

@version { version number } 版本号
@warning { warning message } 警告
@$
@@
@@
@&
@~
@<
@>
@#
@%
生成列表:
 在每个行的开始处以“-”打头，以下缩进对齐，列表每项也以“-”打头。

        下面是Doxygen所有的标签：

@a　<word>　用斜体显示后面跟随的一个词
@addindex　(text)
@addtogroup　<name> [(title)]
@anchor <word>　标记锚点
@arg　{ item-description }　@arg @c 参数的描述
@attention  { attention text }　标记需要注意的段落
@author { list of authors }　作者
@b <word> 用粗体显示后面跟随的一个词
@brief {brief description} 概要
@bug { bug description } 臭虫
@c <word> 打字机字体
@callgraph  
@category <name> [<header-file>] [<header-name>] Object-c Only
@class <name> [<header-file>] [<header-name>] 类
@code
@cond [<section-label>]
@copydoc <link-object>
@date { date description } 日期
@def <name> 宏描述
@defgroup <name> (group title)
@deprecated { description } 废弃的
@dir [<path fragment>]
@dontinclude <file-name>
@dot
@dotfile <file> ["caption"]
@e <word> 斜体字
@else
@elseif <section-label>
@em <word> 斜体字
@endcode
@endcond
@enddot
@endhtmlonly
@endif
@endlatexonly
@endlink
@endmanonly
@endverbatim
@endxmlonly
@enum <name> 描述enum,比如:
/*! @enum Test::TEnum
 * A description of the enum type.
 */

@example <file-name> 例子文件
@exception  <exception-object> { exception description }异常描述
@f$  公式
@f[  公式
@f]  公式
@file [<name>] 文件说明
@fn (function declaration) 函数说明
@hideinitializer
@htmlinclude
@htmlonly 后面的东西原封不动的插入生成的html当中,直到遇到 @endhtmlonly
@if <section-label>
@ifnot <section-label>
@image <format> <file> ["caption"] [<sizeindication>=<size>]
@include <file-name>
@includelineno <file-name>
@ingroup (<groupname> [<groupname> <groupname>])
@internal
@invariant
@interface
@latexonly
@li
@line
@link <link-object>
@mainpage
@manonly
@n 强制新行
@name (header)
@namespace
@nosubgrouping
@note { text }
@overload [(function declaration)]
@p 打字机字体
@package
@page
@par
@paragraph
@param
@post
@pre
@private (PHP only)
@privatesection (PHP only)
@property
@protected (PHP only)
@protectedsection (PHP only)
@protocol
@public (PHP only)
@publicsection (PHP only)
@ref <name> ["(text)"]
@relates
@relatesalso
@remarks { remark text }
@return
@retval
@sa =@see
@section
@see
@showinitializer
@since
@skip
@skipline
@struct
@subsection
@subsubsection
@test { paragraph describing a test case }
@throw
@todo { paragraph describing what is to be done }
@typedef
@union
@until
@var
@verbatim
@verbinclude
@version { version number }
@warning { warning message }
@weakgroup
@xmlonly
@xrefitem
@$
@@
@@
@&
@~
@<
@>
@#
@%