如何在Python中记录字段和属性？

Question

在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中使用呢？

Answer 1

在类的文档字符串中自由地记录可以访问的属性，或者把它们变成属性。你已经正确地记录了属性，问题可能出在2.x版本和旧式类上，这些旧式类不支持描述符——在这种情况下，记得从object继承。

Answer 2

在Python解释器中使用help查看属性的文档对我来说很好用，具体可以参考属性文档。注意：IPython的魔法帮助命令?并没有显示属性的文档字符串。

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:

    bar property

在Sphinx中，你必须使用:members:指令来记录属性，详细信息可以查看autodoc文档。对我来说，这个方法非常有效！

如果使用:members:，Sphinx也会记录属性。属性的文档字符串可以作为注释放在属性前面，格式是用冒号跟在井号后面，比如#: foo属性。根据Sphinx的autodoc文档：

对于模块的数据成员和类的属性，文档可以放在带有特殊格式的注释中（用#:来开始注释，而不是仅仅用#），或者放在定义后的文档字符串中。注释需要单独占一行在定义之前，或者紧接着赋值在同一行。后者的形式仅限于一行。

Answer 3

Python有一个叫做PEP 257的规范，专门讲述文档字符串的约定。关于属性的文档，它提到：

在模块、类或者__init__方法的最顶层，简单赋值后紧跟着的字符串字面量被称为“属性文档字符串”。

所以下面的内容被认为是有文档说明的属性：

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

(编辑：修正了第二个文档字符串)