如何正确记录类的静态变量？

Question

在类中记录静态变量的首选方法是什么？

class Foo(object):
    """
    Foo doc.
    """

    bar = 'bar'
    """
    Bar doc.
    """


class Foo(object):
    """
    Foo doc.
    """

    # Bar doc.
    bar = 'bar'

还有什么...？

Answer 1

无法将文档字符串与变量关联。 PEP添加属性文档字符串失败。

用于代码文档编制的最佳方法可能是注释而不是文档字符串，因此您不会引入PEP讨论的那种歧义。如果需要help()和docs，则可以在类的文档字符串中另外记录它们。

Answer 2

Epydoc文档工具确实提供了对可变文档字符串的支持：

http://epydoc.sourceforge.net/manual-docstring.html#variable-docstrings

格式与您上面建议的一样：

如果变量赋值语句后紧跟一个裸字符串文字，则该赋值将被视为该变量的文档字符串

Answer 3

我个人使用Google风格的DocString格式，而我对静态属性的处理方法是将其包括在类的DocString中。

例如

class Bicycle:
    """
    A class defining a Bicycle

    Attributes:
        NUM_WHEELS (int): The number of wheels that a bicycle has: 2.
    """
    NUM_WHEELS = 2

尽管这绝对是一个自以为是的话题。根据您希望属性显示的可见性，也可以仅使用属性定义上方的常规注释来记录它们。例如：

class Bicycle:
    """
    A class defining a Bicycle
    """
    # The number of wheels that a bicycle has
    NUM_WHEELS = 2