Python中docstring文档的写法

该写法根据Python的PEP 257文档总结。

类的函数称为方法（method），模块里的函数称为函数（function）

1. 每一个包，模块，类，函数，方法都应该包含文档，包括类的__init__方法
2. 包的文档写在__init__.py文件中
3. 文档有单行文档和多行文档
4. 单行文档：
   1. 不要重复函数的声明语句，例如：function(a, b) -> list
   2. 指明做什么和返回什么，例如Do X and return a list.
   3. 使用三引号，方便换行
5. 多行文档：
   1. 如果模块是一个脚本，也就是单文件程序，模块的文档应该写明脚本的使用方法
   2. 模块的文档需要写明包含的类，异常，函数
   3. 如果是包，在__init__.py中，写明包里面包含的模块，子包
   4. 如果是函数或类方法，应该写明函数或方法的作用，参数，返回，副作用，异常和调用的限制等
   5. 如果是类，写明类的行为，和实例参数，构造方法写在__init__中
   6. 使用三引号，而且两个三引号都应该单独成行

单行例子：

def function(a, b):
    """Do X and return a list."""

多行例子：

def complex(real=0.0, imag=0.0):
    """Form a complex number.
    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

未经许可请不要转载。