11

一方では、フィールドを作成するだけで、他の言語でモデル化された追加のアクセサー関数でPythonクラスを覆わないようにすることをお勧めします。

一方、「属性docstrings」のPEPは拒否されました。

第三に、epydocとsphinxはそれらをサポートします。非建設的な質問のリスクがありますが、クラス内の変数を文書化するための単一の明確で一般的な方法はありますか？

4

1 に答える 1

6

私はそうするように頼まれたので、私のコメントを答えとして言い換えます。

一般に、インスタンス（パブリック）属性は自明であり、ユーザーによるそれらの使用法はドキュメントを必要としません。属性の名前とコンテキストは、属性が何であるかを明確にするのに十分であり、クラスのドキュメントでその処理方法に関するドキュメントを少し追加できます。

ユーザーに属性へのアクセスを提供したいが、属性が十分に自明ではない、および/またはその処理に注意が必要な状況が発生する可能性があります（正しく処理されない場合、「物事を爆破する」可能性があるため） ）。

たとえば、属性を使用できるようにするには、属性に特定の「インターフェース」が必要であることをユーザーに知らせたい場合があります。または、属性が満たす必要のある条件を説明する必要があります。

この場合、ドキュメントをクラスのドキュメントと一緒にすることはお勧めできません。クラスのドキュメントはますます長くなり、多くの非常に具体的な知識を説明しているからです。

シンプルで、よりエレガントな解決策は、プロパティを使用することです。プロパティを使用すると、属性にdocstringを追加して、属性へのアクセスを実際に制御する方法を提供できるため、クラスをより堅牢にすることができます。

多くの属性を処理する必要がある場合は、数十のプロパティを作成するのは面倒かもしれませんが、たとえばデコレータを使用して、それらを動的に追加することはできます。これは、常に同じ種類のゲッター/セッターを使用してdocstringを追加する場合に特に効果的です。

たとえば、次のように書くことができます。

def set_properties(names_to_docs):
    def decorator(cls):
        for name, doc in names_to_docs.items():
            prop = property((lambda self: getattr(self, '_{}'.format(name))),
                            (lambda self, val: setattr(self, '_{}'.format(name), val),
                            doc=doc)
            setattr(cls, name, prop)
        return cls
    return decorator

そして、次のように使用します。

>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
...     def __init__(self):
...         self._a = 1
...         self._b = 2
... 
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1

コメントの中で、Lukas Grafは、Zope.interfaceを使用して、具体的なクラスを単純に記述するクラスを作成できると指摘しました。これにより、属性にdocstringを追加する機会が得られます。これはおそらく他のオプションでしょう。私はZope.interfaceの使用経験がないので、何ができるのか、どのように、そして最終的には自動ドキュメント化プログラムとどのように相互作用するのかを正確に知ることはできません。

于 2012-10-02T22:05:25.010 に答える