पायथन संपत्ति पर डॉकस्ट्रिंग डालने का सही तरीका क्या है?

Question

क्या मुझे कई दस्तावेज़ बनाना चाहिए, या केवल एक (और मुझे इसे कहां रखना चाहिए)?

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

मुझे लगता है कि property() एक डॉक्टर तर्क स्वीकार करता है।

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 

>>> 

ध्यान दें कि सेटर के docstring "सेट x" नजरअंदाज कर दिया है।

तो आपको इसे देखने के लिए गेटर फ़ंक्शन पर संपूर्ण संपत्ति (गेटर और सेटर) के लिए डॉकस्ट्रिंग लिखनी चाहिए। एक अच्छा संपत्ति 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

अक्सर संपत्तियों को डॉकस्ट्रिंग की आवश्यकता नहीं होती है, उनका व्यवहार आत्म-स्पष्टीकरण होना चाहिए।

लेकिन अगर आपको वास्तव में वहां एक डॉकस्ट्रिंग डालने की ज़रूरत है, तो इसे गेटर पर रखें। यदि आप दोनों को एक पर डालते हैं, तो सेटटर से एक को फिर भी पाइडोक द्वारा अनदेखा कर दिया जाएगा।

यदि आप उदाहरण के लिए अपने सेट ऑपरेशन में कुछ चेक करते हैं और शायद अपवाद फेंकते हैं, तो उस व्यवहार को दस्तावेज करने के लिए वहां एक डॉकस्ट्रिंग डालने के लिए एक अच्छा अनुनाद होगा। लेकिन डॉकस्ट्रिंग के रूप में बस कुछ सेट करना "सेट/spam का मान प्राप्त करता है" पूरी तरह बेकार है।