web-dev-qa-db-ja.com

パラメーターを使用してメソッドを文書化する方法は？

Pythonのドキュメント文字列を使用して、パラメーターを使用してメソッドをドキュメント化する方法は？

EDIT：PEP 257 はこの例を示します：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

これはほとんどのPython開発者が使用している規則ですか？

Keyword arguments:
<parameter name> -- Definition (default value if any)

私は次のようなもう少し形式的なものを期待していました

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

環境：Python 2.7.1

pythondocumentationdocumentation-generation
119
David Andreoletti

私の経験に基づいて、 numpy docstring Conventions （PEP257スーパーセット）は、最も広く普及しているfollowed規則でもあります Sphinx などのツールによる。

一例：

Parameters
----------
x : type
    Description of parameter `x`.
76
Vladimir Keleshev

規約：

ツール：

更新：Python 3.5以降では、 type hints を使用できます。これは、コンパクトで機械可読な構文です。

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

この構文の主な利点は、言語によって定義され、明確であることです。そのため、PyCharmなどのツールはこの構文を簡単に活用できます。

32
Jakub

python doc文字列はfree-formです。好きな方法でドキュメント化できます。

例：

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

現在、いくつかの規則がありますが、pythonはそれらを強制しません。一部のプロジェクトには独自の規則があります。 docstringを操作するためのいくつかのツールも特定の規則に従います。

10
nosklo

Sphinxを使用してコードを文書化する予定がある場合は、「署名」機能を使用して、パラメーター用に適切にフォーマットされたHTMLドキュメントを生成できます。 http://sphinx-doc.org/domains.html#signatures

8
Kyle Mede

ここでのその他の回答が既に指摘しているように、主流はおそらく Sphinxの方法 であるため、後でSphinxを使用してこれらの派手なドキュメントを生成できます。

そうは言っても、私は個人的にインラインコメントスタイルで行くことがあります。

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

ここにもう1つ例を示します。いくつかの小さな詳細をインラインで文書化します。

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

利点（@ mark-horvathが別のコメントで既に指摘したように）は次のとおりです。

  • 最も重要なことは、パラメーターとそのドキュメントが常に一緒に留まることで、次の利点があります。
  • 少ない入力（変数名を繰り返す必要はありません）
  • 変数の変更/削除時のメンテナンスが容易になります。いくつかのパラメータの名前を変更した後、Orphanパラメータのドキュメントパラグラフはありません。
  • 不足しているコメントを見つけやすくなります。

現在、このスタイルは「 "い」と思われるかもしれません。しかし、「ugい」は主観的な言葉だと思います。もっと自然な方法は、このスタイルは主流ではないので、あまり馴染みがないように見えるかもしれません。繰り返しますが、「快適」は主観的な言葉でもあります。しかし、ポイントは、上記のすべての利点が客観的であることです。標準的な方法に従えば、それらを達成することはできません。

いつか将来的には、このようなインラインスタイルも使用できるドキュメントジェネレーターツールがあることを願っています。それが採用を促進します。

PS：この答えは、私が適切だと思うときはいつでもインラインコメントを使用するという私自身の好みに由来しています。 辞書を文書化するのと同じインラインスタイル も使用します。

2
RayLuo

Docstringsは、対話型環境内でのみ有用です。 Pythonシェル。インタラクティブに使用されないオブジェクト（内部オブジェクト、フレームワークコールバックなど）を文書化する場合、通常のコメントも使用できます。インデントされたコメントをそれぞれの行に配置するために私が使用するスタイルは次のとおりです。そのため、コメントが適用されることがわかります。

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

Docstringではこのようなことはできません。

0
Lawrence D'Oliveiro