文件字串就是三引號字串,所謂三引號字串是指前後用三個引號圍起來的內容。
下面示範三引號字串,引號用雙引號或單引號皆可,倒是開頭用三個雙引號的話,結尾也要用三個雙引號,例如
"""這是文件字串
第二行
第三行"""
單引號的情況也一樣,例如
'''這是文件字串
第二行
第三行'''
三引號字串可以跨行或單行,對於開頭跟結尾的三個引號都沒有硬性規定要放在跟文字同一行或單獨一行,這裡保持程式碼的一致風格即可。
在函數 (function) 中定義文件字串 (docstring) 是放在關鍵字 (keyword) def 的下一行,此例的 demo() 函數不做任何事情。
def demo():
"""此函數不做任何事情"""
pass
#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:docstring01.py
# 功能:示範函數的文件字串
# 作者:張凱慶
在類別 (class) 中定義文件字串是放在關鍵字 class 的下一行,至於在方法 (method) 中定義文件字串也是放在關鍵字 def 的下一行,下例的 Demo 類別僅作示範用。
class Demo:
"""此類別僅作示範用"""
def demo():
"""此方法僅作示範用"""
pass
#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:docstring02.py
# 功能:示範函數的文件字串
# 作者:張凱慶
我們進到互動式介面來看看文件字串該寫些什麼內容,利用預設屬性 (attribute) __doc__ ,也就是被前後兩條底線包圍的 __doc__ 屬性就能取得文件字串,這裡利用 print() 函數印出 int() 函數的文件字串。
從這裡可以看到,文件字串大致上分成兩個部分,第一個部分為使用例子, int() 函數有兩種參數 (parameter) 的用法,空一行後為第二個部分,第二個部分就是使用說明,這裡 int() 函數是將參數回傳為整數型態。
相關教學影片