数据的文档字符串？

Question

有没有办法像文档字符串（docstring）描述模块或函数那样，来描述模块的数据呢？

class MyClass(object):
    def my_function():
        """This docstring works!"""
        return True
    my_list = []
    """This docstring does not work!"""

Answer 1

正如codeape所说，无法对一般的数据成员进行文档说明。

不过，可以对property类型的数据成员进行文档说明：

class Foo:
  def get_foo(self): ...

  def set_foo(self, val): ...

  def del_foo(self): ...

  foo = property(get_foo, set_foo, del_foo, '''Doc string here''')

这样就可以给foo这个属性添加说明文字，显而易见。

Answer 2

可以使用epydoc语法来为模块的数据编写文档。Epydoc是Python中最常用的文档工具之一。

编写文档的语法是在变量初始化的那一行上方加上#:，像这样：

# module.py:

#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"

现在，当你生成文档时，data会被描述为模块变量，并附上相应的描述和类型str。你可以省略@type这一行。

Answer 3

据我所知，模块的数据成员是不能直接加文档字符串的。

PEP 224 提出了这个功能，但这个提案被拒绝了。

我建议你在模块的文档字符串中说明模块的数据成员：

# module.py:
"""About the module.

module.data: contains the word "spam"

"""

data = "spam"