doxygen 解析支持的标签规范

doxygen 解析支持的标签规范 目录 1. 1. 2. 3. 4. 5. 6. 2. 3. dox 常用命令 dox 文献信息 dox 状态信息 dox 模块信息 dox 函式信息 dox 提醒信息 dox 关联信息 dox 标签格式 dox 注释风格
6. dox 常用命令
讲述基本的常用标签命令
6.1. dox 文献信息
@author ... 作者 @brief ... @file ... 摘要 文件声明
6.2. dox 状态信息
@version ... 版本推荐使用$Id$ @todo ... 改进,可以指定针对的版本
6.3. dox 模块信息
@var ... 模块变量 说明 @typedef ... 模块变量类型说明
6.4. dox 函式信息
@param p ... 参数 p 说明 @arg ... 列表说明参数 信息
@return ... 返回值说明


@retval ... 返回值类型说明
6.5. dox 提醒信息
@note ... 注解 @attention ... 注意 @bug ... @warning ... 问题 警告
6.6. dox 关联信息
@sa ... 参考资料
7. dox 标签格式
约定文档化标签的语法
 
epydoc 支持两种标签的语法！ doxygen: \tag 内容...

Javadoc: @tag 内容...

为了简化学习，在新浪标准化开发中我们推荐统一使用
@tag: 内容... 格式
8. dox 注释风格
约定文档化标签放置
 
依照 C/C++ JAVA 类别语言注释风格自然的进行 /**


                            
*
一个示范类，描述在此
*/ class Test{ public: /** * 一个 enum. * 详细描述可以多行 */ enum TEnum { TVal1, /**单行注释*/ } *enumPtr, /**< enum pointer. Details. */ /** * 构造器函式 * 详细描述可以多行 */ Test(); /** * 一个普通函式 描述和参数等等的叙述 * @param a 整数参数 * @param s 字串指针参数 * @see Test() 参看.. * @return 返回值描述 */ int testMe(int a,const char *s); /** * 纯虚成员函式 * @see testMe() 参看 * @param c1 第一参数


           o    o    o        o o o o o o o
* @param c2 第二参数 */ virtual void testMeToo(char c1,char c2) = 0; /** * 一个公共变量 * 详细描述 */ int publicVar; }; DoxyGen 支持多种注释声明,仅仅是在标准基础上添加一点儿: JavaDoc 样式的: /** * ... text ... */ Qt 样式的: /*! ... text ... */ C++ 样式的: /// /// ... text ... /// or //! //! ... text ... //! 我们推荐简化的 Qt 风格 /*! 引发的多行注释 ... */ 正常結束
块结构


 
象文章分章节一样 注释文本也能定义各种语义区块
12.1. 段落
           o o
@par 命令引出
/*! \class Test 普通文字 @par 用户定义第一段.
段落可以包含多行 @par */
具体实例参考:
这是第二段. 段落间通过空行来区分
@par 命令 输出的 HTML
12.2. 列表
          o
@li 命令引发 可以混合其它格式命令
@li \c AlignLeft left alignment. @li \c AlignCenter center alignment. @li \c AlignRight right alignment 无类型的列表项也支持
具体实例参考:
@li 命令
12.3. 章节
 
@section 命令引发 不过，只能在 @page 命令后作用


               
即通过 @page 命令，声明创建一个相关页面，内容将组织到最终的“相关页面”中， 与 Todo Bug 列表页面等等并列在一起!
例如 /*! @page page1 A documentation page Leading text. @section sec An example section This page contains the subsections \ref subsection1 and \ref subsection2. For more info see page \ref page2. @subsection subsection1 The first subsection Text. @subsection subsection2 The second subsection More text. */ /*! @page page2 Another page Even more info. */
 o o   
将生成:
@page 命令
包含了
@section 章 @subsection 节 @ref 提及 三个命令的使用
12.4. 引用块
  o o o o o o o
@code 和 @endcode 框出
类似:
/*! ... @par _doAllOnLoad() @param 全局数组 g_onload
@return void 逐条调用已知的函数^_^
@note
动态加载的模块中,一些函数需要 onLoad()事件触发;但是


o o o o
@code window.onload= new Function ("myFunctoin();"); @endcode 将会重新注册 onLoad() 事件的运行函数,致使不能简单的使不同的 模块中需要的不确定数目的 onLoad()触发函数叠加注册!
o o o
... */
13. 行内修饰

简单的字体声明
13.1. @b
  o
@b 文字
生成:
<b>文字</b>
13.2. @c
  o
@c 文字
生成:
<tt>文字</tt>
13.3. @n
  o
@n
生成:
<br/>
13.4. 特殊标签

针对 PHP 语言，doxygen 有几个标签命令，需要关注


13.4.1. PHP 代码说明专用
    
@private 私有的 @protected 保护的 @public 公开的
是独立说明项的声明标签 用以说明 类/函式/变量 的具体性质
13.4.2. PHP 章节内容专用
    
@privatesection 私有的章节 @protectedsection 保护的章节 @publicsection 公开的章节 是@page 附加说明页面内容中的声明标签
用以领起不同性质的 类/函式/变量 说明内容
14. 警告

当然对于意外情况， doxygen 不会崩溃，只是进行警告，你可以根据 log 日志文件 的提示进行修正





。