Question

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

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

Answer 1

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

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

我建议您在模块的docstring中记录模块的数据成员：

# 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属性提供文档字符串。

Docstrings数据？

3 个答案: