文档化开发注释规范

Contents

原则
文档化标签
1. 基础标签命令
2. 输出美化控制
反馈

1. 原则

在语言要求的地方注释，以标准的注释语法!
- 我们禁止惊奇！一切规范化到谁都可以准确的猜测出正确的结果最好！(就象 FreeBSD 的组织方式...)
注释说明必要的信息，我们不期望精彩的小说在注释中诞生!
- 适当的版本标识
  - 尽量使用CVS等版本管理系统自动提供的解析
  - 因为如果自个儿来写的话难以统一修改
- 适当的设计思路描述
- 适当的算法设计描述

2. 文档化标签

由于开发语言非常丰富，所以选择了最通用和稳定的文档化工具来支持:
1. - DoxyGen 是种支持 C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及 PHP, C# and D 等等语言的文档化工具.
  - 成熟，功能强大,支持广泛
  - 甚至于提供了图形界面的管理工具
  - 对于所有支持多行注释的语言其实都可以应用
2. epydoc
  - 是纯Python 实现的 Python 专用文档化工具
  - 与Python 结合非常自然，稳定，可扩展

2.1. 基础标签命令

仅仅列举我们推荐使用的文档化标签,进一步的标签命令,请自行进入相关页面学习

EpyDoc注释规范

DoxyGen注释规范

epydoc 解析支持的标签规范

Contents

py常用命令
py标签格式
py注释风格

3. py常用命令

讲述基本的常用标签命令

3.1. py文献信息

@author: ...	作者
@license: ...	版权
@contact: ...	联系

3.2. py状态信息

@version: ...	版本推荐使用$Id$
@todo [ver]: ...	改进,可以指定针对的版本

3.3. py模块信息

@var v: ...	模块变量v 说明
@type v: ...	模块变量类型v 说明

3.4. py函式信息

@param p: ...	参数 p 说明
@type v: ...	参数 p 类型说明
@return: ...	返回值说明
@rtype v: ...	返回值类型说明

3.5. py提醒信息

@note: ...	注解
@attention: ...	注意
@bug: ...	问题
@warning: ...	警告

3.6. py关联信息

@see: ...

参考资料

4. py标签格式

约定文档化标签的语法

epydoc 支持三种标签的语法！
Epytext:
```
 @tag: 内容...
```
ReStructuredText:
```
 :tag: 内容...
```
Javadoc:
```
 @tag 内容...
```
为了简化学习，在新浪标准化开发中我们推荐统一使用
```
 @tag: 内容...
```
格式

5. py注释风格

约定文档化标签放置

依照Python 本身的注释风格自然的进行
```
   1 # OtTool.py文件(模块)头部
   2 """Otter Tools main script
   3 @version: $Id$
   4 @author: U{Zoom.Quiet<mailto:[email protected]>}
   5 @see: 参考资料链接等等
   6 """
   7 import sys,string
   8 class ottool:
   9     """Otter Tools 主类
  10         - 组织其它小工具，完成任务
  11     @todo: 计划完成……
  12     """
  13     def __init__(self):
  14         """调用相关模块，初始化(当前比较简单，对象初始化时就完成所有任务)
  15             - 应用 OtCUI 参数理解;获得有效变量
  16         """
  17         self.cui = OtCUI.otcui()
  18 ...
```
__init__.py 中的注释成为包文档
文件头部注释成为模块文档
紧贴 class 声明后的注释成为类文档
紧贴 def 声明后的注释成为函式文档

-- ZoomQuiet (2005-01-26)

{EpydocApiTag }^e

doxygen 解析支持的标签规范

Contents

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 第一参数
       * @param c2 第二参数
       */
       virtual void testMeToo(char c1,char c2) = 0;
      /** 
       * 一个公共变量
       * 详细描述
       */
       int publicVar;
};

DoxyGen 支持多种注释声明,仅仅是在标准基础上添加一点儿:

JavaDoc 样式的:
- ```
 /**
 * ... text ...
 */
```
Qt 样式的:
- ```
 /*!
 ... text ...
 */
```

C++ 样式的:

/// 
 /// ... text ...
 ///
 or
 //!
 //! ... text ...
 //!

我们推荐简化的 Qt 风格

  /*! 
  引发的多行注释 
  ...
  */
  正常結束

-- ZoomQuiet (2005-01-26)

{DoxygenApiTag }^e

8.1. 输出美化控制

可以通过简单的约定来美化文档的输出
- 但是不要深迷于此

EpyDoc注释输出控制

DoxyGen注释输出控制

Contents

块结构
行内修饰
1. 特殊标签
  1. URLs
  2. 交叉引用
警告

9. 块结构

象文章分章节一样
注释文本也能定义各种语义区块

9.1. 段落

简单的使用空行就好

 def example():
    """
    这是第一段.  段落可以包含多行并可以包含有I{行内修饰}
    
    这是第二段. 段落间通过空行来区分
    """
    [...]

将生成为:

这是第一段. 段落可以包含多行并可以包含有行内修饰 这是第二段. 段落间通过空行来区分

9.2. 列表

象MoinMoin 等等结构化文本一样,通过缩进来声明,使用数字或是 “-” 来引导列表项
可以混合

 def example():
    """
    此为段落.
      1. 此为列表项
        - 此为子列表
        - 子列表第二项
            - 此为次层列表,同样可以继续列表下去
            - 只要有一致的缩进

      2. 此为列表第二项
         可以包含段落和测试引用

         >>> print '此为测试引用语句'
         此为测试引用语句

         此为第二段
    """
    [...]

将生成文档为:

此为段落.

此为列表项
- 此为子列表
- 子列表第二项
  - 此为次层列表,同样可以继续列表下去
  - 只要有一致的缩进
此为列表第二项
- 可以包含段落和测试引用
  >>> print '此为测试引用语句' 此为测试引用语句此为第二段

9.3. 章节

使用 ReStructuredText 结构化文本的声明方式

 def example():
    """
    此段不在任何章节中.

    第 1 章
    =========
      这为第 1 章中的段落

      章节 1.1
      -----------
      此为章节 1.1 中的段落

    第 2 章 
    =========
      此为第 2 章 中的段落.
    """
    [...]

将生成:

此段不在任何章节中.

9.3.1. 第 1 章

这为第 1 章中的段落

9.3.1.1. 章节 1.1

此为章节 1.1 中的段落

9.3.2. 第 2 章

此为第 2 章中的段落.

9.4. 引用块

同样是利用ReStructuredText 的引用声明

 def example():
    """
    使用“：：”引出引用块::
    
        原文 /
            / 引用块

    此为在引用块后的段落
    还是空行来区分.
    """
    [...]

生成的文档类似:

使用“：：”引出引用块:
```
    
        原文 /
            / 引用块
```
此为在引用块后的段落还是空行来区分.

10. 行内修饰

简单的字体声明

 def example():
    """
    I{B{行内修饰} 可以嵌套} 在多行内.

      - I{斜体}
      - B{加重}
      - C{源代码}

    C{my_dict={1:2, 3:4}}.
    """
    [...]

将生成类似文档:

行内修饰 可以嵌套在多行内.
- 斜体
- 加重'
- 源代码
```
   1     my_dict={1:2, 3:4}
```

10.1. 特殊标签

10.1.1. URLs

 def example():
    """
    - U{www.python.org}
    - U{http://www.python.org}
    - U{The epydoc homepage<http://
      epydoc.sourceforge.net>}
    - U{The B{I{Python}} homepage
      <www.python.org>}
    - [U{Edward Loper<mailto:edloper@
      gradient.cis.upenn.edu>}
    """
    [...]

对应生成文档:

www.python.org
http://www.python.org
The epydoc homepage
The Python homepage
Edward Loper <edloper AT gradient DOT cis DOT upenn DOT edu>

10.1.2. 交叉引用

L{text<object>}
可以自动生成到其它对象的文档页面链接
text 处是说明文字
<object> 是具体对象的名称，类/函式/变量名

11. 警告

当然对于意外情况， epydoc 不会崩溃，只是进行警告，你可以根据提示进行修正

ZoomQuiet (2005-01-27)

{EpydocMarkup }^e

Contents

块结构
行内修饰
警告

12. 块结构

象文章分章节一样
注释文本也能定义各种语义区块

12.1. 段落

@par 命令引出

 /*! \class Test
    普通文字
    
    @par    用户定义第一段.
    段落可以包含多行
    
    @par    这是第二段. 段落间通过空行来区分
 */

具体实例参考:
- @par 命令
- 输出的HTML

12.2. 列表

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

将生成:
- @page 命令
- 包含了
  - @section 章
  - @subsection 节
  - @ref 提及三个命令的使用

12.4. 引用块

@code 和 @endcode 框出

类似:

/*!
...
@par _doAllOnLoad()
@param  全局数组 g_onload
@return void 逐条调用已知的函数^_^

@note   动态加载的模块中,一些函数需要onLoad()事件触发;但是
@code   window.onload= new Function ("myFunctoin();");
@endcode

将会重新注册 onLoad() 事件的运行函数,致使不能简单的使不同的模块中需要的不确定数目的 onLoad()触发函数叠加注册!
...
*/

13. 行内修饰

简单的字体声明

13.1. @b

@b 文字
生成:
- <b>文字</b>

13.2. @c

@c 文字
生成:
- <tt>文字</tt>

13.3. @n

@n
生成:
- <br/>

13.4. 特殊标签

针对PHP语言，doxygen 有几个标签命令，需要关注

13.4.1. PHP代码说明专用

@private 私有的
@protected 保护的
@public 公开的
是独立说明项的声明标签
用以说明类/函式/变量的具体性质

13.4.2. PHP章节内容专用

@privatesection 私有的章节
@protectedsection 保护的章节
@publicsection 公开的章节
是@page 附加说明页面内容中的声明标签
用以领起不同性质的类/函式/变量说明内容

14. 警告

当然对于意外情况， doxygen 不会崩溃，只是进行警告，你可以根据log 日志文件的提示进行修正

ZoomQuiet (2005-01-27)

{DoxygenMarkup }^e

15. 反馈

请汇集自个儿的使用体验

-- ZoomQuiet (2005-01-25)