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
    ...

未經許可請不要轉載。