如何在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文档记录字段或属性呢？

- deamon

---

此前曾提到过这一点。在《被遗弃、撤回和被拒绝的PEP》中有相关内容：http://www.python.org/dev/peps/pep-0224/。 - janislaw

可能是在Python的属性上放置文档字符串的正确方法是什么？的重复提问。 - Stevoisiak

Answer 1

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

（编辑：修复了第二个文档字符串）

- Eli Bendersky

---

我也在想，Sphinx也是如此。 - Jochen Ritzel

很好，因为Sphinx是如今Python文档的事实标准工具。 - Eli Bendersky

这是关于属性docstrings的PEP（224）。 - Josie Thompson

晚来的评论，但我认为很重要：标准库的 help 函数未显示属性文档字符串。 - Serge Ballesta

“帮助”函数无法显示“属性文档字符串”的文档，因为它们在运行时不会被保留。根据PEP 257的规定：“它们不被Python字节码编译器所识别，并且不能作为运行时对象属性访问（即不会分配给__doc__）。” - typeracer

PEP 224 在2001年被拒绝了。正确的参考是 PEP 257。 - Franklin Yu

Answer 2

使用help在Python解释器中对属性进行文档化对我很有效，参见属性文档。注意：IPython的魔术帮助运算符?未显示属性docstring。

>>> 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 documentation。如果使用：members：，那么属性也将被Sphinx记录下来。属性的docstrings可以作为属性前的注释给出，但要使用井号后跟冒号，例如#：foo属性。参见Sphinx autodoc文档所述：对于模块数据成员和类属性，文档可以放在一个特殊格式的注释中（使用#：开头的注释），或者放在定义之后的docstring中。注释需要在定义之前单独一行或者在同一行上赋值之后立即添加。后一种形式仅限于一行。

- Mark Mikofski

Answer 3

在类的文档字符串中自由地记录可访问属性或将其创建为属性。如果你已经正确地记录了属性，问题可能出现在2.x和旧式类中，它们不支持描述符——在这种情况下继承 object。

- Cat Plus Plus

Answer 4

使用Sphinx注释或Restructured Text编写文档字符串，可以自动生成漂亮的文档。它还支持函数参数和返回值 - 据我所知没有字段，但你可以轻松地为它们创建一个列表。

- Sebastian Blask