文档化开发注释规范

文档化开发注释规范

目录

1. 原则
2. 文档化标签
   1. 基础标签命令
3. py常用命令
   1. py文献信息
   2. py状态信息
   3. py模块信息
   4. py函式信息
   5. py提醒信息
   6. py关联信息
4. py标签格式
5. py注释风格
6. dox常用命令
   1. dox文献信息
   2. dox状态信息
   3. dox模块信息
   4. dox函式信息
   5. dox提醒信息
   6. dox关联信息
7. dox标签格式
8. dox注释风格
   1. 输出美化控制
9. 块结构
   1. 段落
   2. 列表
   3. 章节
      1. 第 1 章
         1. 章节 1.1
      2. 第 2 章
   4. 引用块
10. 行内修饰
    1. 特殊标签
       1. URLs
       2. 交叉引用
11. 警告
12. 块结构
    1. 段落
    2. 列表
    3. 章节
    4. 引用块
13. 行内修饰
    1. @b
    2. @c
    3. @n
    4. 特殊标签
       1. PHP代码说明专用
       2. PHP章节内容专用
14. 警告
15. 反馈

原则

• 在语言要求的地方注释，以标准的注释语法!

  • 我们禁止惊奇！一切规范化到谁都可以准确的猜测出正确的结果最好！(就象 FreeBSD 的组织方式...)

• 注释说明必要的信息，我们不期望精彩的小说在注释中诞生!
  • 适当的版本标识
    • 尽量使用CVS等版本管理系统自动提供的解析
    • 因为如果自个儿来写的话难以统一修改
  • 适当的设计思路描述
  • 适当的算法设计描述

 

文档化标签

• 由于开发语言非常丰富，所以选择了最通用和稳定的文档化工具来支持:

  1. 

     • DoxyGen 是种支持 C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及 PHP, C# and D 等等语言的文档化工具.

     • 成熟，功能强大,支持广泛
     • 甚至于提供了图形界面的管理工具
     • 对于所有支持多行注释的语言其实都可以应用

  2. epydoc

     • 是纯Python 实现的 Python 专用文档化工具
     • 与Python 结合非常自然，稳定，可扩展

 

基础标签命令

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

EpyDoc注释规范

DoxyGen注释规范

epydoc 解析支持的标签规范

目录

1. py常用命令
   1. py文献信息
   2. py状态信息
   3. py模块信息
   4. py函式信息
   5. py提醒信息
   6. py关联信息
2. py标签格式
3. py注释风格

py常用命令

讲述基本的常用标签命令

py文献信息

@author: ...

作者

@license: ...

版权

@contact: ...

联系

 

py状态信息

@version: ...

版本推荐使用$Id$

@todo [ver]: ...

改进,可以指定针对的版本

 

py模块信息

@var v: ...

模块变量v 说明

@type v: ...

模块变量类型v 说明

 

py函式信息

@param p: ...

参数 p 说明

@type v: ...

参数 p 类型说明

@return: ...

返回值说明

@rtype: ...

返回值类型说明

 

py提醒信息

@note: ...

注解

@attention: ...

注意

@bug: ...

问题

@warning: ...

警告

 

py关联信息

@see: ...

参考资料

 

py标签格式

约定文档化标签的语法

• epydoc 支持三种标签的语法！

• Epytext:

  @tag: 内容...

• ReStructuredText:

  :tag: 内容...

• Javadoc:

  @tag 内容...

• 为了简化学习，在新浪标准化开发中我们推荐统一使用

  @tag: 内容...

  格式

 

py注释风格

约定文档化标签放置

• 依照Python 本身的注释风格自然的进行
• 切换行号显示

     1 # OtTool.py文件(模块)头部   2 """Otter Tools main script   3 @version: $Id$   4 @author: U{Zoom.Quiet<mailto:[e-mail]>}   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 ...  19 

• __init__.py 中的注释成为包文档

• 文件头部注释成为模块文档
• 紧贴 class 声明后的注释成为类文档
• 紧贴 def 声明后的注释成为函式文档

---

-- ZoomQuiet (2005-01-26)