当前位置: 首页 > POX > 正文

书写Python的API文档

书写Python的API文档

Python和其它编程语言一样也有文档规范,编程时只要按照规范来写docstring,就可以利用pydoc工具从python程序中生成API文档,类似于java中的javadoc。

1.doctring的位置

  • 包的Docstring位于包内的init.py文件的开头。
  • 模块的Docstring位于模块所在文件的开头。
  • 函数的Docstring位于函数名称所在行的下一行,函数体之前。
  • 类的Docstring位于类的名称所在行的下一行,所有描述之前。

Docstring对应以上对象的doc属性。如果没有编写Docstring,则doc属性的值为None。可以使用help()时会显示doc属性的内容,也就是显示我们书写的docstring。

2.docstring的书写规则

通用规则

Docstring用三重双引号包围,如果取消转义,前边加r,如果使用Unicode,前边加u。

Docstring前后是否添加空白行,要依据Docstring的主体的布局而定。例如,对于类,因为有很多成员函数,每个函数直接要用空行隔开。所以也要在Docstring前后增加空行。但是去看官方的实现,他们只在后边增加了空行而已。

但是,对于函数,因为一般情况下,函数体内是没有空行的,所以不需要增加空行。但对于特别复杂的函数,可能函数体也有空行,这时就需要在Docstring前后(仅后边?)增加空行了。

单行的Docstring:

应该鲜明的指出以下两点或者其中一点:

  • 做什么(Do X)。
  • 返回什么(Return Y),应该包含返回类型。
  • 例如:”””Do X and return a list.”””

不应该描述:

  • 函数签名(例如:”””function(a, b) -> list”””。Python的* * 函数签名可以通过自省得到,显式的函数签名一般用于C语言函数)。
  • 函数的内部实现。

多行Docstring:

多行Docstring从第二行开始,每一行都应与起始的三重双引号对齐。
多行Docstring应该具有以下结构:

  • 三重双引号。
  • 单行概述,类似于单行Docstring所做的。(这两行可以合为一行)
  • 空白行。
  • 详细描述。
  • 空白行。
  • 三重双引号

不对类型的代码实体,Docstring的侧重点不同:

  • 对于脚本程序:Docstring应该详尽的描述脚本的使用方法。同时兼顾新老使用者。
  • 对于模块:Docstring应该罗列出模块的输出对象:例如类、函数、错误异常。每个对象对应一行简略的描述(应该比次对象的Docstring的概述行更加简略一些)。
  • 对于包:Docstring应该罗列出包中的模块与子包。
  • 对于函数或者方法:Docstring应该描述其功能、参数(应该每个参数占一行,按顺序列出,并且指明默认值)、返回值、副作用、可能产生的异常错误、调用其的限制条件。It should be documented whether keyword arguments are part of the interface.
  • 对于类:Docstring应该描述其功能、Public方法以及实例变量。如果这个类创建时就打算被继承,并提供了接口的话,那么要单独描述其接口。如果这个类继承了其他类并且与父类的关系密切,Docstring需要提及继承关系并说明与父类的不同(使用override和extend)。

本文固定链接: http://sdnhub.cn/index.php/write-python-docstring/ | 软件定义网络SDN

该日志由 sdnhub 于2014年06月16日发表在 POX 分类下, 你可以发表评论,并在保留原文地址及作者的情况下引用到你的网站或博客。
原创文章转载请注明: 书写Python的API文档 | 软件定义网络SDN
关键字:

书写Python的API文档:等您坐沙发呢!

发表评论

*

快捷键:Ctrl+Enter