文档化开发注释规范

原则

文档化标签

基础标签命令

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

EpyDoc注释规范

DoxyGen注释规范

epydoc 解析支持的标签规范

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:Zoom.Quiet@gmail.com>}
       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)

doxygen 解析支持的标签规范

dox常用命令

讲述基本的常用标签命令

dox文献信息

@author ...

作者

@brief ...

摘要

@file ...

文件声明

dox状态信息

@version ...

版本推荐使用$Id$

@todo ...

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

dox模块信息

@var ...

模块变量 说明

@typedef ...

模块变量类型说明

dox函式信息

@param p ...

参数 p 说明

@arg ...

列表说明参数 信息

@return ...

返回值说明

@retval ...

返回值类型说明

dox提醒信息

@note ...

注解

@attention ...

注意

@bug ...

问题

@warning ...

警告

dox关联信息

@sa ...

参考资料

dox标签格式

约定文档化标签的语法

  • epydoc 支持两种标签的语法!
  • doxygen:

     \tag 内容...
  • Javadoc:

     @tag 内容...
  • 为了简化学习,在新浪标准化开发中我们推荐统一使用
     @tag: 内容...
    格式

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)

输出美化控制

EpyDoc注释输出控制

DoxyGen注释输出控制

块结构

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

段落

  • 简单的使用空行就好
  •  def example():
        """
        这是第一段.  段落可以包含多行并可以包含有I{行内修饰}
        
        这是第二段. 段落间通过空行来区分
        """
        [...]
  • 将生成为:


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

列表

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

  • 可以混合
  •  def example():
        """
        此为段落.
          1. 此为列表项
            - 此为子列表
            - 子列表第二项
                - 此为次层列表,同样可以继续列表下去
                - 只要有一致的缩进
    
          2. 此为列表第二项
             可以包含段落和测试引用
    
             >>> print '此为测试引用语句'
             此为测试引用语句
    
             此为第二段
        """
        [...]
  • 将生成文档为:


此为段落.

  1. 此为列表项
    • 此为子列表
    • 子列表第二项
      • 此为次层列表,同样可以继续列表下去
      • 只要有一致的缩进
  2. 此为列表第二项
    • 可以包含段落和测试引用

      >>> print '此为测试引用语句' 此为测试引用语句 此为第二段

章节

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

  •  def example():
        """
        此段不在任何章节中.
    
        第 1 章
        =========
          这为第 1 章中的段落
    
          章节 1.1
          -----------
          此为章节 1.1 中的段落
    
        第 2 章 
        =========
          此为第 2 章 中的段落.
        """
        [...]
  • 将生成:


  • 此段不在任何章节中.

第 1 章

  • 这为第 1 章中的段落

章节 1.1

  • 此为章节 1.1 中的段落

第 2 章

  • 此为第 2 章 中的段落.

引用块

  • 同样是利用ReStructuredText 的引用声明

  •  def example():
        """
        使用“::”引出引用块::
        
            原文 /
                / 引用块
    
        此为在引用块后的段落
        还是空行来区分.
        """
        [...]
  • 生成的文档类似:


  • 使用“::”引出引用块:

            原文 /
                / 引用块
    此为在引用块后的段落 还是空行来区分.

行内修饰

  • 简单的字体声明
  •  def example():
        """
        I{B{行内修饰} 可以嵌套} 在多行内.
    
          - I{斜体}
          - B{加重}
          - C{源代码}
    
        C{my_dict={1:2, 3:4}}.
        """
        [...]
  • 将生成类似文档:


  • 行内修饰 可以嵌套 在多行内.

    • 斜体

    • 加重'

    • 源代码

       1     my_dict={1:2, 3:4}
    

特殊标签

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>}
        """
        [...]
  • 对应生成文档:


交叉引用

  • L{text<object>}

  • 可以自动生成到其它对象的文档页面链接
  • text 处是说明文字

  • <object> 是具体对象的名称,类/函式/变量 名

警告

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


ZoomQuiet (2005-01-27)

块结构

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

段落

  • @par 命令引出
  •  /*! \class Test
        普通文字
        
        @par    用户定义第一段.
        段落可以包含多行
        
        @par    这是第二段. 段落间通过空行来区分
     */
  • 具体实例参考:

列表

  • @li 命令引发
  • 可以混合其它格式命令
  •   @li \c AlignLeft left alignment.
      @li \c AlignCenter center alignment.
      @li \c AlignRight right alignment
      
      无类型的列表项也支持
  • 具体实例参考:

章节

  • @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 提及 三个命令的使用

引用块

  • @code@endcode 框出

  • 类似:
    • /*!
      ...
      @par _doAllOnLoad()
      @param  全局数组 g_onload
      @return void 逐条调用已知的函数^_^
      
      @note   动态加载的模块中,一些函数需要onLoad()事件触发;但是
      @code   window.onload= new Function ("myFunctoin();");
      @endcode
      
      将会重新注册 onLoad() 事件的运行函数,致使不能简单的使不同的模块中需要的不确定数目的 onLoad()触发函数叠加注册!
      ...
      */

行内修饰

  • 简单的字体声明

@b

  • @b 文字

  • 生成:
    • <b>文字</b>

@c

  • @c 文字

  • 生成:
    • <tt>文字</tt>

@n

  • @n

  • 生成:
    • <br/>

特殊标签

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

PHP代码说明专用

  • @private 私有的

  • @protected 保护的

  • @public 公开的

  • 是独立说明项的声明标签
  • 用以说明 类/函式/变量 的具体性质

PHP章节内容专用

  • @privatesection 私有的章节

  • @protectedsection 保护的章节

  • @publicsection 公开的章节

  • @page 附加说明页面内容中的声明标签

  • 用以领起不同性质的 类/函式/变量 说明内容

警告

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


ZoomQuiet (2005-01-27)

反馈


-- ZoomQuiet (2005-01-25)

CodeCommentingRule (last edited 2009-12-25 07:17:54 by localhost)