#!/usr/bin/python
# Filename: func_doc.py
def printMax(x, y):
'''Prints the maximum of two numbers.
The two values must be integers.'''
x = int(x) # convert to integers, if possible
y = int(y)
if x > y:
print x, 'is maximum'
else:
print y, 'is maximum'
printMax(3, 5)
print printMax.__doc__
(源文件:code/func_doc.py)
輸出
$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
The two values must be integers.
它如何工作
在函數(shù)的第一個(gè)邏輯行的字符串是這個(gè)函數(shù)的 文檔字符串 。注意,DocStrings 也適用于模塊和類,我們會(huì)在后面相應(yīng)的章節(jié)學(xué)習(xí)它們。
文檔字符串的慣例是一個(gè)多行字符串,它的首行以大寫字母開始,句號(hào)結(jié)尾。第二行是空行,從第三行開始是詳細(xì)的描述。 強(qiáng)烈建議 你在你的函數(shù)中使用文檔字符串時(shí)遵循這個(gè)慣例。
你可以使用doc(注意雙下劃線)調(diào)用 printMax 函數(shù)的文檔字符串屬性(屬于函數(shù)的名稱)。請(qǐng)記住 Python 把 每一樣?xùn)|西 都作為對(duì)象,包括這個(gè)函數(shù)。我們會(huì)在后面的類一章學(xué)習(xí)更多關(guān)于對(duì)象的知識(shí)。
如果你已經(jīng)在 Python 中使用過 help(),那么你已經(jīng)看到過 DocStings 的使用了!它所做的只是抓取函數(shù)的doc屬性,然后整潔地展示給你。你可以對(duì)上面這個(gè)函數(shù)嘗試一下——只是在你的程序中包括 help(printMax)。記住按 q 退出 help。
自動(dòng)化工具也可以以同樣的方式從你的程序中提取文檔。因此,我 強(qiáng)烈建議 你對(duì)你所寫的任何正式函數(shù)編寫文檔字符串。隨你的 Python 發(fā)行版附帶的 pydoc 命令,與 help()類似地使用 DocStrings。