|
@class 声明一个类
@fn 声明一个函数
@brief 简要说明
/**
@file RenderMgr.h @brief 渲染管理类 @date 3/16/2006 @author lethean */
@param 声明一个参数
@note 注解
@par paragraph，自定义一个段落标题，类似html中<p>
@code 代码示例，需要用@endcode封闭，代码段中不需要加前置*号
/** @brief 读取bmp文件 @remarks 测试一下 @param [in] dc 传入一个dc用于临时操作 @param [in] filename bmp文件名 @note 屏幕dc只能在一处被使用，请确保传入屏幕dc后其他地方不会操作该dc @par 代码示例: @code //使用 CDC* dc = AfxGetMainWindow()->GetDC(); Bitmap bmp( dc , "test.bmp"); AfxGetMainWindow()->ReleaseDC( dc ); @endcode */
对于单行的前置注释可以用///，或者/** blahblah */ 样式
///我是一个变量
int index;
对于单行的后置注释，需要加一个"<"符号
int count; ///< 我也是
/** 协议标识 */
enum ProtoId { PROTOID_LOGIN, /**< 登陆协议*/ PROTOID_BROWSE, /**< 浏览协议*/ };
@defgroup是用来定义新模块的
集中在某个头文件中定义所有的模块，然后在属于这个模块的类定义处使用@ingroup
EnginePrerequisite.h中
/**
@defgroup Render Render渲染模块 @defgroup Resource Resource管理模块 @defgroup Sound Sound声音模块 @defgroup Anim Anim动画模块 @defgroup Math Math数学库模块 @defgroup Script Script脚本模块 */
RenderMgr.h中
/**
@class RenderMgr
@ingroup Render
*/
JavaDoc类型： /** * ... 程序注释 ... */ Qt类型： /*! * ... 程序注释... */ 单行型式： /// 这是一个简洁型的注释 //! 这也是一个简洁型的注释 用Doxygen的这几种基本注释类型就可以建立足以建立文档了，如果需要更多复杂功能，Doxygen还可以提供高级格式如组（group）和列表。 Doxygen的常用注释参数：
Doxygen的使用，如下： E:\>xstring目录包含下列文件： Xstring.cpp Xstring.h 其中xstring.h里对xstring类的StrToInt方法的注释如下： /** * 0. 序言 Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（包括前两篇文章介绍的log4cpp和CppUnit）都使用了doxygen文档系统。而国内的开发人员却使用的不多，这里从开发人员使用的角度介绍这个工具，使开发人员用最少的代价尽快掌握这种技术，并结合这个工具探讨如何撰写注释的问题。以下以linux下的C++语言为例进行介绍，以下讨论基于doxygen1.3.3。 1. doxygen使用步骤 Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件： 让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。 OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下面的命令，相应的文档就会产生在指定的目录中。 需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。 2. doxygen配置文件 对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。 TAG 缺省值 含义 3. doxygen注释 注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。 3.2 doxygen常用注释格式 对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下： 进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。 对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式： 3.3 doxygen常用注释命令 到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。 4. 注释的书写 推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点： 虽然使用各种IDE或者Source Insight 可以方便地在windows下阅读和分析C/C++代码，但是一步步Go to Definetion 实在令人痛苦。Doxygen能够生成函数调用关系图，所有的函数调用关系可以一目了然，另外他还能统计文档中所有的类，成员变量，成员函数等。总的来说，Doxygen不但能从局部把握代码，还能从全局审视代码，后者是一般IDE和Source Insight 不能做到的。所以，使用doxygen阅读分析代码可以达到事半功倍的效果。 doxygen的安装很简单，到官方网站下载doxygen的windows安装程序即可。除了安装doxygen外，还需要安装graphviz，因为doxygen需要使用graphviz的dot.exe生成调用图。graphviz在它的官方网站上也可以下载到安装程序。不过我下载的安装程序在安装时老是报cab文件错误。最后我下载了graphviz的release文件，即安装程序下面的zip压缩文件，下载完成后解压缩即可。 安装完doxygen后即可进行适当的配置，然后运行doxyfile生成文档。基本的配置前人早有说明，不再赘述。需要注意的是： 1.要勾选Dot选项卡下面的HAVE_DOT、CALL_GRAPH 、CALLER_GRAPH 选项。并在DOT_PATH下面填入dot.exe的路径，也就是graphviz安装目录下的bin文件夹。 2.勾选Wizard->Project选项卡下面的Scan recursively！ 3.勾选Build选项卡下面的EXTRACT_ALL、EXTRACT_PRIVATE、EXTRACT_STATIC、EXTRACT_LOCAL_CLASSES、EXTRACT_LOCAL_METHODS选项 4.如果程序里面有中文，将Project选项卡下的DOXYFILE_ENCODING和Input选项卡下面的INPUT_ENCODING改为GBK 5.可以勾掉LATEX输出，这样节省编译时间 5. 参考资料 2. doxygen manual 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4. 6. 使用doxygen |
Doxygen+Graphviz 帮助
Doxygen+Graphviz 帮助
Doxygen+Graphviz 帮助
2010-02-02 10:33