將文檔字符串放在Python屬性上的正確方法是什么？

Question

我應該制作幾個文檔字符串，還是僅存一個（我應該把它放在哪里）？

@property
def x(self):
     return 0
@x.setter
def x(self, values):
     pass

我看到property()接受了doc參數。

Answer 1

在getter上寫docstring，因為1）這是help(MyClass)顯示的內容，2）它也是如何在Python文檔中完成的- 請參閱x.setter示例 。

關於1）：

class C(object):
    @property
    def x(self):
        """Get x"""
        return getattr(self, '_x', 42)

    @x.setter
    def x(self, value):
        """Set x"""
        self._x = value

然后：

>>> c = C()
>>> help(c)
Help on C in module __main__ object:

class C(__builtin__.object)
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)
 |
 |  x
 |      Get x

>>>

請注意，將忽略setter的docstring“Set x”。

因此，您應該在getter函數上為整個屬性（getter和setter）編寫docstring，以使其可見。 良好屬性docstring的示例可能是：

class Serial(object):
    @property
    def baudrate(self):
        """Get or set the current baudrate. Setting the baudrate to a new value
        will reconfigure the serial port automatically.
        """
        return self._baudrate

    @baudrate.setter
    def baudrate(self, value):
        if self._baudrate != value:
            self._baudrate = value
            self._reconfigure_port()