一方面，我们被鼓励只创建字段，而不是用模仿其他语言的额外访问器函数来封装我们的python类。
另一方面，"属性文档字符串"的PEP被拒绝。
第三方面，epydoc和斯芬克斯支持他们。冒着非结构化问题的风险，是否有一种单一、清晰、通用的方法来记录类中的变量？
由于我被要求这样做，我将我的评论改写为答案。
通常，实例(公共)属性是不言自明的，用户使用它们不需要文档。属性的名称和上下文足以明确属性是什么，您可以在类的文档中添加一些关于如何处理它的文档。
在某些情况下，您可能会希望为用户提供对属性的访问权限，但该属性不够不言自明，并且/或者其处理需要注意(因为如果处理不正确，可能会"搞砸")。
例如，您可能想让用户知道一个属性应该有一个特定的"接口"，以便使用它。或者，您必须解释属性必须满足的条件。
在这种情况下，将文档与类的文档放在一起不是一个好主意，因为类的文档越来越长，它解释了很多真正具体的知识。
我认为，简单且更优雅的解决方案是使用属性。属性允许您向属性添加一个文档字符串，为您提供了一种实际控制对其访问的方法，从而使类更加健壮。
如果你必须处理很多属性，那么写几十个属性可能会很麻烦，但你仍然可以动态添加它们，例如使用装饰器。这样做效果很好，尤其是如果您只想添加一个docstring，并且总是使用相同类型的getter/setter。
例如，你可以写：
def set_properties(names_to_docs):
def decorator(cls):
for name, doc in names_to_docs.items():
prop = property((lambda self: getattr(self, '_{}'.format(name))),
(lambda self, val: setattr(self, '_{}'.format(name), val),
doc=doc)
setattr(cls, name, prop)
return cls
return decorator
并像这样使用：
>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
... def __init__(self):
... self._a = 1
... self._b = 2
...
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1
Lukas Graf在评论中指出，您可以使用Zope.interface创建一个简单描述具体类的类，这使您有机会向属性添加文档字符串。这可能是另一种选择。我没有使用Zope.interface的经验，所以我不能确切地说出你能做什么，如何做，以及它最终如何与自动文档程序交互。