Doxygen的使用

 

1．  Doxygen的使用

1）  创建及设置配置文件

doxygen –g

然后手动修改配置文件

或采用Doxygen的GUI界面的Doxywizard配置向导工具

 

INPUT             设置源码文件夹

FILE_PATTERNS   设置文件过滤，如处理C语言：*.cpp *.h

RECURSIVE        对于递归分析源文件树，必须设置为YES           

EXCLUDE和EXCLUDE_PATTERNS  用于在INPUT中排除部分，如测试的代码不用处理

INPUT_ENCODING          为Doxygen能处理中文，设置为 GB2312

DOXYFILE_ENCODING      为Doxygen能处理中文，设置为 GB2312

 

PROJECT_NAME        Project 的名字，以一个单字为主，多个单字请使用双引号括住。

PROJECT_VERSION    Project的版本号码

INLINE_ SOURCES   如果设定为YES ，则程序代码也会被嵌入于说明文件中。

2）特殊的注释

一种特殊的注释就是增加额外标识的C/C++注释块，这样doxygen就知道将其加入文档中了，有多种注释方法，因为我用C/C++，所以推荐以下表达方法：

特殊注释有两种：一种detail描述，另一种brief描述；

顾名思意，一个brief只描述一行，detail描述则是更长更详尽；

两种描述都有几种表达方式，这里只介绍推荐使用的方式：

 

Detail描述：

使用JavaDoc风格，包含一个C风格的注释块

/**

  * ... text ...

  */

用///开头，描述一行注释

/// Detailed description

 

brief描述：

是用于描述一行信息，此信息用于简单描述对象，在生成的文档中，可以在检索目录中的简介。

       注意每一部分，只允许一个detail或brief描述。

 

3）结构内注释

如果需要为file，struct，union，class或enmu的members添加注释，并且你需要将这些注释放在compound之内，可以考虑将注释块放在member的后面。这样就要在注释块中添加一个“<”标记。

如：

enum TEnum

{

              TVal1, ///< Enum value TVal1.

              TVal2, ///< Enum value TVal2.

              TVal3  ///< Enum value TVal3.

        }

 

4）  特殊控制注释

以上注释一般都在模块之前或之后，以及struct等中间的说明。Doxygen提供了其它一些控制指令，可以在任何地方增加注释。命令格式如下：

 

@commands

 

有如下命令：

@struct to document a C-struct.

@union to document a union.

@enum to document an enumeration type.

@fn to document a function.

@var to document a variable or typedef or enum value.

@def to document a #define.

@file to document a file

@author  作者的信息

@date    2008/01/01

@param     参数说明

@return    说明该函数的传回值

5）  Lists列表

在每行的开始处以“-”大头，从下缩进对齐，列表每项也以“-”打头。

 

  /**

   *  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.

   */

 

处理显示为：

 

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.

 

使用“.”可以结束一个list。