Каков правильный способ поставить docstring на свойство Python?

Ответ 1

Запишите docstring на getter, потому что 1), что показывает help(MyClass), и 2) это также как это сделано в Python docs - см. пример 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

>>>

Обратите внимание, что параметр docstring set set "Set x" игнорируется.

Итак, вы должны написать docstring для всего свойства (getter и setter) в функции getter, чтобы он был видимым. Примером хорошей строки 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()

Ответ 2

Часто свойствам не требуется docstring, их поведение должно быть самоочевидным.

Но если вам действительно нужно поставить docstring, поместите его в getter. Если вы поместите один на оба, один из сеттера будет проигнорирован pydoc в любом случае.

Если вы, например, выполняете некоторые проверки в своей заданной операции и, возможно, генерируете исключение, то это будет хороший резонанс, чтобы поставить документацию для документирования этого поведения. Но просто иметь что-то вроде "set/получает значение spam", поскольку docstring совершенно бесполезен.