pythonの属性docstringはよく使われていますか？

Question

一方で、フィールドを作成するだけでなく、他の言語でモデル化されたアクセサアクセサを追加してPythonクラスを隠さないことが推奨されます。

一方、PEP for 'attribute docstrings'は拒否されました。

第3の手では、epydocとsphinxがサポートされています。非構造的な質問のリスクがある場合、クラス内の変数を文書化するための単一の、明確な、一般的なプラクティスがありますか？

Answer 1

私はそうするように求められて以来、私の答えは答えとして言い換えます。

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

ユーザに属性へのアクセスを提供したいが、その属性が十分に自明ではなく、かつ/または取り扱いに注意が必要な場合もあります（正しく処理されないと、爆発物を上げる "）。

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

この場合、ドキュメントをクラスのドキュメントと一緒に置くのは良い考えではありません。クラスのドキュメントが長くなったり長くなったりして、実際に多くの知識が説明されているからです。

シンプルで、より洗練されたソリューションは、プロパティを使用することです。 プロパティを使用すると、属性とにドキュメントストリングを追加することで、実際のアクセスを制御することができ、クラスをより堅牢にすることができます。

多くの属性を処理する必要がある場合は、数十のプロパティを書き込むのが面倒かもしれませんが、デコレータなどを使用して動的に追加することもできます。 これは特に、常に同じ種類のゲッタ/セッタを使用して、ドキュメントストリングを追加したいだけの場合にうまく機能します。あなたが書くことができる。例えば

：

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 

そして、このようにそれを使用する：ルーカス・グラーフは、あなたは、単にクラスを作成するZope.interfaceを使用できることを指摘したコメントで

>>> @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 

具体的なクラスについて説明します。これにより、ドキュメントストリングを属性に追加することができます。これはおそらく他の選択肢になります。 私はZope.interfaceの使い方に慣れていないので、あなたができることと方法、そしてそれが最終的に自動ドキュメンテーションプログラムとどのようにやりとりするかを正確に伝えることはできません。