～～學習進度表～～

文件字串 (documentation string) 定義在模組 (module) 、函數 (function) 、類別 (class) 及方法 (method) 中，用為程式的說明文件，可用預設屬性 (attribute) __doc__ 存取

說明文件不外是解釋程式某部分的使用方式，通常會舉出簡單的例子，傳統程式語言 (programming language) 的說明文件大都是額外編寫，印成紙書或放在網路供人查詢，或是以註解 (comment) 形式加進原始程式碼 (source code) 中， Python 文件字串的特點讓程式設計師可以邊寫程式邊查文件，無須翻紙書或查網路。

我們先進入 IDLE 的 Python Shell 來看看吧！下面印出整數型態 int 的屬性 __doc__

int 是內建整數型態的識別字 (identifier) ，因此回傳一個整數物件 (object) ，這裡可以看到內建函數 int() 的解釋與用法。

其實 int 是型態名稱，也就是整數類別的識別字， int() 也就是建立整數型態的建構子 (constructor) ，不過 Python 官方把這些內建型態的建構子歸到內建函數一類，因此這裡一樣稱 int() 為內建函數。

下面再來看看串列 (list) 的文件字串

串列的文件字串只有簡單解釋用法，用字面常數 (literal) 、物件變數或識別字名稱都可以叫出文件字串，前提是有設置文件字串。大體上文件字串是依需要來設置。文件字串分成兩種，一種是單行的文件字串，另一種則是多行，下面我們以簡單例子分別介紹模組、函數以及類別的文件字串撰寫位置。

文件字串用三引號定義，首先看到模組的文件字串，需要寫在未縮排的地方，並且放到檔案開頭，例如

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"""這是模組文件字串
   僅作示範用
   第三行"""

# 印出模組的文件字串
print(__doc__)

# 檔名: doc_demo01.py
# 說明:《Python入門指南》的範例程式
# 網站: http://kaiching.org
# 作者: 張凱慶
# 時間: 2023 年 5 月

第 1 行到第 3 行為文件字串定義的地方，文件字串採用連續三個引號，也就是字串前後都用三個引號圍起來，跟字串一樣，單引號或雙引號都可以

 1
 2
 3

"""這是模組文件字串
   僅作示範用
   第三行"""

通常文件字串的第一行說明功能，第二行之後提供使用範例，不過各個開發團隊的文件字串需求都不太一樣，因此這裡僅作示範用。

第 6 行直接印出內建屬性 __doc__

 6

print(__doc__)

執行結果如下

函數或方法的文件字串寫在關鍵字 (keyword) def 的下一行，以下以函數當示範

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 定義函數
def do_something():
    """這是函數文件字串
       僅作示範用
       第三行"""
    pass

# 印出函數的文件字串
print(do_something.__doc__)

# 檔名: doc_demo02.py
# 說明:《Python入門指南》的範例程式
# 網站: http://kaiching.org
# 作者: 張凱慶
# 時間: 2023 年 5 月

關鍵字 def 之下就是文件字串

 2
 3
 4
 5

def do_something():
    """這是函數文件字串
       僅作示範用
       第三行"""

第 9 行直接印出函數的 __doc__ 屬性

 9

print(do_something.__doc__)

執行結果如下

以上注意文件字串會依原始版面編排，上面由於第二行之後的縮排格數較多，因此會有比較多的空格。

類別的文字字串同樣是放在關鍵字 class 之下，例如

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 定義類別
class ClassDemo21:
    """這是類別文件字串
       僅作示範用
       第三行"""
    pass

# 印出類別的文件字串
print(ClassDemo21.__doc__)

# 檔名: doc_demo03.py
# 說明:《Python入門指南》的範例程式
# 網站: http://kaiching.org
# 作者: 張凱慶
# 時間: 2023 年 5 月

關鍵字 class 之下就是文件字串

 2
 3
 4
 5

class ClassDemo21:
    """這是類別文件字串
       僅作示範用
       第三行"""
    pass

這裡第 9 行同樣直接印出類別的 __doc__ 屬性

 9

print(ClassDemo21.__doc__)

執行結果如下

到這裡 Python 基礎已經講得差不多了，不過我們還有三個關鍵字 async 、 await 及 with 沒提到，因為這幾個關鍵字通常要跟標準程式庫 (standard library) 一起用，所以接下來我們來概略介紹標準程式庫囉！