python - docstringの記述-関数の引数と戻り値を指定する

Question

たとえば、次のような関数があるとします。

>>> def foo(a):
        return a+1

そのためのドキュメント文字列を書きたいです。

docstringでaを取り、a + 1を返すことを指定する際の規則は何ですか？

Answer 1

docstringの考え方は、それがどのように発生するかについてあまり話さずに、ユーザーに何が起こっているのか、何が出ているのかについての基本的な概要を提供することです。この場合：

def foo(a):
    """Take a number a and return its value incremented by 1."""
    return a + 1

ささいな例として、関数の文書化に関するDiveIntoPythonのセクションにある例が好きです。

def build_connection_string(params):
    """Build a connection string from a dictionary of parameters.

    Return string."""

明らかに、より複雑な関数には、より大きなdocstringが必要です。docstringが、それがどのように起こっているか（実装の詳細を含めるべきではない）ではなく、何が起こっているか（何が渡され、何が返されるか）について話していることを確認してください。

Answer 2

PEP 257が役立つはずです！

Answer 3

Pythonの慣習（これと他のトピックについて）については、最初にPython拡張提案を試すことをお勧めします。

Python PEP 257は、次のように関数を指定する1行のdocstringを提案しています。

def function(a, b):
"""Do X and return a list."""

しかし、これは好きではありません：

def function(a, b):
"""function(a, b) -> list"""

後者の例は他の方法で割り出すことができるからです。

それらを一瞥しただけですが、PEPからのリンクは、docstringの核心に入る他のPEPに移動するように見えます。

一般的な注意として、Pythonの設計上の決定と哲学に関する興味深いトピックがいくつかあるので、まだ読んでいない場合はPEPを参照します。

Answer 4

私は個人的にビルトインが使用するスタイルが好きです。

>>> help（len）

len（...）

len(object) -> integer

Return the number of items of a sequence or mapping.