docstringsの書き込み - 関数の引数と返品を指定します

StackOverflow https://stackoverflow.com/questions/4524450

  •  13-10-2019
  •  | 
  •  

質問

私が関数を持っていると仮定します、たとえば：

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

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

ドックストリングでA+1を返すことをドックストリングで指定する際の条約は何ですか？

役に立ちましたか？

解決

Docstringのアイデアは、ユーザーに、それがどのように起こるかについてあまり多くのことを伝えずに、出て行っていることの基本的な概要を提供することです。この場合：

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

あまり些細な例としては、私はそのものが好きです 文書化関数についてPythonのセクションに飛び込みます。

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

    Return string."""

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

他のヒント

PEP 257 助けてください！

Pythonの規則（このトピックおよびその他のトピックについて）については、最初にPython Enhancement Proposalsを試すことをお勧めします。

Python PEP 257 1つの行Docstringsがあなたの関数を次のように指定することを提案します：

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

しかし、このようではありません：

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

後者の例は他の手段で分割できるためです。

それらをちらっと見ただけでしたが、PEPからのリンクは、Docstringsの核心に入る他のPEPに行くように見えます。

一般的なメモとして、Pythonの設計上の決定と哲学に関する興味深いトピックがいくつかあるので、まだおもちゃを閲覧します。

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

>>>ヘルプ（レン）

レン（...）

len(object) -> integer

Return the number of items of a sequence or mapping.
ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top