不完整翻译

基本原理

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表示重载函数中调用父类函数。
  • 使用正确的参数名。最好一个参数一行。

缩进

略。