不完整翻译
基本原理
PEP257 目标是约定文档字符串的顶层结构:包括什么,如何展现(不牵涉具体语法)。此 PEP 不关心语法。
具体说明
什么是文档字符串
文档字符串是字面意义上出现在 module、function、class、method 定义的第一条文本。文档字符串因此会变成该对象的__doc__
属性。
所有模块(module)、函数(function)、类(class)以及类的公共方法(public method)都应该有文档字符串(docstring)。
另外,总是用三个双引号来包住文档字符串。"""docstring"""
or r"""docstring\ another line"""
or u"""unicode"""
单行文档字符串
用于非常显然的情况。
- 即使一行也用三个引号
- 六个引号在同一行
- 前后无空行
- 文档字符串是一个短语。提示函数或方法的影响,如“do this” “return that”,而非描述“return the pathname”。
-
不应该是函数或方法参数的“签名”(这是内省的),如:
def function(a, b): """function(a, b) -> list""" return [a, b]
只有使用 C 函数这类参数无法内省的函数的时候才列出参数。返回值无法内省,因此需列出。
def function(a, b): """ Do X and return a list""" return [a, b]
多行文档字符串
- 多行字符串包括一行单行文档类似的摘要,后面是一行空行以及更详细的描述。一行摘要用于自动化工具;因此确保摘要只有一行同时后面有空行是必要的。摘要可以与引号同一行也可以在引号下一行。整个文档字符串与引号相同缩进。
- 类文档字符串后要加一个空行。因为类方法之间都要有空行。
- 脚本的文档字符串应该可以作为其“usage”字符串使用……
- 模块的文档字符串需要列出其暴露的类、异常和函数,每一项包括一行摘要。包的文档字符串(
__init__.py
) 也需要包括其暴露的模块和子包。 - 函数或方法的文档字符串需要简要列出其行为、参数、返回值、副作用、异常以及调用约束。可选参数也需要指出。
- 类的文档字符串需要列出其行为、公有方法以及属性。基类用于子类的接口需要分离列出。
- 子类继承自父类的方法以及其区别需要在文档字符串中列出。使用
override
表示函数重载,extend
表示重载函数中调用父类函数。 - 使用正确的参数名。最好一个参数一行。
缩进
略。