文檔字元串

5.5 文檔字元串

開發者在編寫函數或模塊時不光要自己能看懂，在和他人合作共同開發或者被他人調用時也需要他人也能看懂。這個時候就可以為自己編寫的函數、模塊或者類添加相應的文檔字元串(docstring)進行說明瞭。
一般的，如果想要在模塊中添加模塊文檔字元串，則需要在模塊的最上方用3個雙引號引住內容，這部分內容則自動會被識別為模塊的文檔字元串。
註意：模塊文檔字元串上方可以有註釋內容，但是不能有任何Python語句，否則不會被識別成模塊文檔字元串。
同理，如果想要在函數中添加文檔字元串，也是需要在定義函數後馬上跟上函數文檔字元串內容。否則也不會被識別成函數文檔字元串。在以後類的定義時也是同理。
放在函數開頭的字元串稱為函數文檔字元串(docstring)，將作為函數的一部分存儲起來。下麵的代碼演示瞭如何給函數添加文檔字元串：

def square(x):
'Calculates the square of the number x.'
return x * x

可以像下麵這樣訪問文檔字元串：
>>> square.doc
'Calculates the square of the number x.'
註意__doc__是函數的一個屬性。屬性名中的雙下劃線表示這是一個特殊的屬性。
示例：為函數添加文檔字元串並對參數進行說明

def frb_num_to_str(p_num, p_is_makeup=False, p_int_num=6):
    """
    將一個int類型或者float類型轉變成str類型。若p_is_makeup為True，則需要補齊為p_int_num位。
    @param p_num: 輸入的參數，一個int類型或者float類型數據
    @param p_is_makeup: 是否要補齊到指定位數
    @param p_int_num: 補齊的指定位數
    @return:
    """
    result = p_num
    if isinstance(p_num, int):
        result = str(p_num)
    elif isinstance(p_num, float):
        result = str(p_num)[:str(p_num).find('.')]
    elif isinstance(p_num, str):
        result = p_num
    # 判斷傳入的num的類型
    if p_is_makeup and len(result) < p_int_num:
        result = '0' * (p_int_num - len(result)) + result
    return result

提示：
為函數、類、模塊自動添加文檔字元串參照Pycharm軟體設置。