python - 数据的文档字符串？

Question

有没有办法以类似于文档字符串描述模块或功能的方式来描述模块的数据？

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

Answer 1

据我所知，不可能将文档字符串分配给模块数据成员。

PEP 224建议使用此功能，但 PEP 被拒绝。

我建议您在模块的文档字符串中记录模块的数据成员：

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

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

可以使用epydoc语法制作模块数据的文档。Epydoc 是 Python 最常用的文档工具之一。

记录的语法#:在变量初始化行的上方，如下所示：

# module.py:

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

现在，当您生成文档时，data将被描述为具有给定描述和类型的模块变量str。您可以省略该@type行。

Answer 3

正如 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属性提供一个文档字符串。