鍍金池/ 教程/ Python/ 使用 DocStrings
備份腳本——版本四
使用 <strong>init</strong> 方法
控制流
異常
表 15.1 一些特殊的方法
如何創(chuàng)建你自己的模塊
使用字典
前言
使用默認(rèn)參數(shù)值
表 5.1 運(yùn)算符與它們的用法
解決問題——編寫一個(gè) Python 腳本
使用 for 語(yǔ)句
使用 continue 語(yǔ)句
使用元組輸出
對(duì)象與參考
使用函數(shù)形參
使用默認(rèn)參數(shù)值
使用 if 語(yǔ)句
如何引發(fā)異常
使用源文件
使用對(duì)象的方法
使用表達(dá)式
定義函數(shù)
使用局部變量
使用列表綜合
使用 sys.argv
使用 lambda 形式
使用 global 語(yǔ)句
備份腳本——版本二
使用列表
使用 while 語(yǔ)句
備份腳本——版本一
使用元組
輸入/輸出
使用類與對(duì)象的變量
使用 sys 模塊
表 5.2 運(yùn)算符優(yōu)先級(jí)
處理異常
使用 break 語(yǔ)句
函數(shù)
基本概念
運(yùn)算符與表達(dá)式
介紹
使用文件
使用序列
接下來(lái)學(xué)習(xí)什么?
使用帶提示符的 Python 解釋器
使用 DocStrings
使用字面意義上的語(yǔ)句
最初的步驟
數(shù)據(jù)結(jié)構(gòu)
儲(chǔ)存與取儲(chǔ)存
使用 dir 函數(shù)
模塊
Python 標(biāo)準(zhǔn)庫(kù)
備份腳本——版本三(不工作?。?/span>
創(chuàng)建一個(gè)類
安裝 Python
面向?qū)ο蟮木幊?/span>
使用模塊的<strong>name</strong>
使用變量和字面意義上的常量
使用繼承

使用 DocStrings


    #!/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。