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

【问题标题】：How to properly document class' static variables?如何正确记录类的静态变量？
【发布时间】：2014-06-04 14:38:12
【问题描述】：

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

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

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


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

    # Bar doc.
    bar = 'bar'

还有什么...？

【问题讨论】：

标签： python coding-style documentation code-documentation

【解决方案1】：

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

代码文档的最佳方式可能是注释而不是文档字符串，这样您就不会引入 PEP 讨论的那种歧义。如果您希望它们在 help() 和文档中，您还可以在课程的文档字符串中记录它们。

【讨论】：

【解决方案2】：

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

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

格式就像你上面建议的那样：

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

【讨论】：

【解决方案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

【讨论】：

我猜是google风格的，静态和非静态属性都列在Attributes:下呢？
类/静态变量记录在类中。实例/非静态变量将记录在 __init__ 方法的 DocString 中。