ドキュメントストリングをPythonプロパティに配置する正しい方法は何ですか？

Question

私はいくつかのドキュメントストリングを作るべきですか、それとも1つしか書いてはいけませんか？

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

私は、property()がdoc引数を受け入れることを確認します。

Answer 1

ゲッターにドキュメントストリングを書くのは、1）それはhelp(MyClass)のもので、2）それはPython docs -- see the x.setter exampleのやり方だからです。 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 

>>> 

注セッターのドキュメント文字列 "×セット" が無視されていること。

getter関数の全プロパティ（getterとsetter）のドキュメントストリングを表示できるようにする必要があります。良いプロパティ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() 

Answer 2

多くの場合、プロパティはドキュメントストリングを必要とせず、その動作は自明でなければなりません。

しかし、実際にドキュメントストリングを置く必要がある場合は、ゲッターに置いてください。両方に1つを入れると、セッターからのものはとにかくpydocによって無視されます。

例えば、あなたのセット操作でいくつかのチェックを行い、おそらく例外をスローすると、その動作を文書化するためにそこにドキュメントストリングを置くことが良い共振になるでしょう。しかし、ちょうど "set/get value of spam"のようなものをdocstringとして使うのは全く役に立たない。