[解決済み] Pythonでフィールドとプロパティを文書化するには？

質問

Pythonでクラスやメソッドをドキュメント化するのは簡単です。

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

しかし、API ドキュメントで使用するためにフィールドやプロパティをどのように文書化するか、あるいは help ?

どのように解決するのですか？

PythonにはPEP( 257 ) があり、Docstring Conventions が定義されています。属性の文書化については、次のように書かれています。

文字列リテラルは 単純な代入の直後に発生する モジュール、クラス、または __init__ メソッドで単純な代入の直後に発生する文字列リテラルを "属性 docstrings"と呼ばれています。

つまり、以下のようなものがドキュメント化された属性とみなされます。

class Foo(object):
  velocity = 1  
  """Foo's initial velocity - class variable"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location - instance variable"""   

(編集: 2番目のdocstringを修正しました)