web-dev-qa-db-ja.com

クラスと__init__ docstringsに何を文書化するべきかについての合意はありますか？

クラスと__init__ docstringsで何をドキュメント化するべきかについてのベストプラクティスは見つかりませんでした。コンストラクタの引数がクラスのdocstringに既に文書化されていることがありますが、__init__ docstringに記述されている場合もあります。これは新しいインスタンスを作成するときに呼び出すものなので、クラスのdocstring内で構成を説明することをお勧めします。しかし、__init__メソッドのdocstringで何を文書化する必要がありますか？

edit：

google styleguide と google docstring style example について知っていますが、どちらも私の質問に答えません。 docstringスタイルの例では、

__init__メソッドは、クラスレベルのドキュメント文字列、または__init__メソッド自体のドキュメント文字列としてドキュメント化できます。どちらの形式でもかまいませんが、2つを混在させないでください。 __init__メソッドを文書化し、それと一致するように1つの規則を選択します。

しかし、__init__関数のdocstringをクラスレベルのdocstringに入れることを選択した場合、__init__ docstringには何を含める必要がありますか？

pythondocstringcode-documentation
31
causa prima

クラスの実際の使用法はSampleClass(args)のようなコマンドによって初期化され、ユーザーはSampleClass.__init__(args)を入力することはないため、エンドユーザーの観点から、混乱した場合、彼らはタイプする可能性がはるかに高い

_help(SampleClass)
_

の代わりに

_help(SampleClass.__init__)
_

したがって、すべてのドキュメントをSampleClassのドキュメント文字列に入れるのは理にかなっていると思います。
そして___init___のdocstring putに"詳細はhelp(SampleClass)を参照してください"誰か（またはプログラム）が偶然に見える場合に備えてそれで。

5
Demis

個人的には、可能な限り google styleguide を使用するようにしています

__init__を使用して新しいインスタンスを作成する場合、初期化されるメンバー変数を文書化する必要があります。そうすれば、他の人は、後でコードでアクセスする必要があるときに何が期待できるかを知っています。

Googleスタイルガイドのサンプル：

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""
4
salomonderossi

その点についてのコンセンサスは知りません。

ただし、 sphinx autodoc モジュールを使用すると、docstringからドキュメントを生成できます。したがって、一貫したdocstring ドキュメンテーション。

あなたの場合、classが何であるかおよびコンストラクタ引数をclassdocstringのように：

class MyClass:
    """I am a class.
    I do funny stuff

    :type tags: dict
    :param tags: A dictionary of key-value pairs
    """

    def __init__(tags):
        self.tags = tags
3
Oleiade

Numpyは__init__クラスドキュメント内。 https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

ここにあなたが見ることができる例があります__init__にはドキュメント文字列がありません。代わりに、クラスドキュメントに表示されます。 https://github.com/numpy/numpy/blob/master/numpy/core/records.py

1
Brig

google docstring example はあなたの質問に答えます。 __init__メソッドをクラスレベルのdocstringにドキュメント化することを選択した場合、__init__ docstringは空のままになります。例えば：

class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:
        Do not include the `self` parameter in the ``Args`` section.

    Args:
        msg (str): Human readable string describing the exception.
        code (:obj:`int`, optional): Error code.

    Attributes:
        msg (str): Human readable string describing the exception.
        code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code

または、このdocstringをクラスレベルと__init__ docstringの間で分割します。

0
geher

Googleには独自のPython用スタイルガイドがありますが、これは参考にしても問題ありません。以下は、doc-stringsのベストプラクティスと見なしているものとのリンクです。 http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

0
coralvanda

PEP 257（docstring PEP）には公式の回答があり、これは間違いなく権威があります。

クラスコンストラクターは、その___init___メソッドのdocstringに文書化する必要があります。

これは関数とメソッドの通常の手順であり、__init__()も例外ではないため、これは非常に論理的です。

その結果、コードとそのドキュメントが同じ場所に配置され、メンテナンスが容易になります。

最後に、ユーザーにドキュメントを表示するツール（Jupyterなど）は、コードのドキュメントを正しく表示する可能性が高くなります。

0
Eric O Lebigot