Python PEP-8戻り値の書式設定

Question

私は具体的な答えを見たことがありませんが、私はPythonドキュメントストリングの戻り値のスタイル規則に関する質問があります。

のような機能を考えてみましょう：

PyCharmで

def foo(ex): 
    output = 2*ex 
    return output 

を、私は、この関数のdocstringを行った場合、それは次のようになります。

def foo(ex): 
    """ 
    Sample text.... 
    :param ex: description... 
    :return: description of return value 
    """ 
    output = 2*ex 
    return output 

私の質問は、私は名前かどうかではありません私の戻り値はdocstringですか？すなわち

：リターン：戻り値の説明

：リターン：出力：戻り値

の説明は、このためのコーディング標準はありか、それは主に個人の好みに任されています？

Answer 1

ドキュメンテーション文字列の規則は、実際にPEP-257で定義されている（とPEP-8は単にそれを参照）が、唯一の一般的なフォーマットは、コンテンツない覆われています。

ドキュメンテーション文字列の内容は、通常Sphinxと呼ばPythonドキュメントジェネレータによって解釈され、スフィンクスに、以下info fieldsが存在する：

• param、parameter、arg、argument、key、keyword：説明パラメータの
• type：パラメータのタイプ。可能であればリンクを作成します。
• raisesraiseexceptexception：その（およびいつ）特定の例外が発生します。
• varivarcvar：変数の説明。
• vartype：変数のタイプ。可能であればリンクを作成します。
• returns,return：戻り値の説明。
• rtype：戻り値の型。可能であればリンクを作成します。

戻り値の型ためrtypeに注意してください。

したがって、戻り値の型はrtypeで指定できますが、オブジェクトの戻り値の実際の（ローカル）名前は無関係です。

Answer 2

すでに言及したように、Python PEPはdocstringの内容をどのように構造化するかを指定していません。しかし、大きなコーディングプロジェクトは、通常、ドキュメントストリングのための独自のガイドラインを持っており、それらのいずれかを適応させることができます。

私は個人的にはナンキーdocstringフォーマット（hereとhere参照）が好きです。戻り値のローカル名は、Numpyスタイルのドキュメントストリングには含まれていません。あなたの関数のdocstringは、次のようになります。

def foo(ex): 
    """One-line function description. 

    Parameters 
    ---------- 
    ex : float 
     Description of parameter. 

    Returns 
    ------- 
    float 
     Description of return value. 

    """ 
    output = 2*ex 
    return output 

numpyのスタイルのドキュメンテーション文字列が同様にSphinxドキュメントジェネレータによってサポートされています。