python中的docstring用法_Python中docstring文档的写法

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

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

每一个包，模块，类，函数，方法都应该包含文档，包括类的__init__方法

包的文档写在__init__.py文件中

文档有单行文档和多行文档

单行文档：

不要重复函数的声明语句，例如：function(a, b) -> list

指明做什么和返回什么，例如Do X and return a list.

使用三引号，方便换行

多行文档：

如果模块是一个脚本，也就是单文件程序，模块的文档应该写明脚本的使用方法

模块的文档需要写明包含的类，异常，函数

如果是包，在__init__.py中，写明包里面包含的模块，子包

如果是函数或类方法，应该写明函数或方法的作用，参数，返回，副作用，异常和调用的限制等

如果是类，写明类的行为，和实例参数，构造方法写在__init__中

使用三引号，而且两个三引号都应该单独成行

单行例子：

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

...

未经许可请不要转载。