पायथन में फ़ील्ड और गुणों को कैसे दस्तावेज़ित करें?

Question

यह एक वर्ग या अजगर में विधि दस्तावेज़ के लिए आसान है:

class Something: 
    """ Description of the class. """ 

    def do_it(self): 
    """ Description of the method. """ 
    pass 

    class_variable = 1 # How to comment? 

    @property 
    def give_me_some_special_dict(self): 
    """ doesn't work! Doc of general dict will be shown. """ 
    return {} 

लेकिन यह कैसे एपीआई दस्तावेज़ या help में उपयोग के लिए एक क्षेत्र या संपत्ति दस्तावेज़ के लिए?

Answer 1

पायथन में एक पीईपी (257) है जो डॉकस्ट्रिंग सम्मेलनों को परिभाषित करता है। विशेषताओं के प्रलेखन के बारे में, यह कहा गया है:

स्ट्रिंग शाब्दिक एक मॉड्यूल, वर्ग या __init__ विधि के शीर्ष स्तर पर एक सरल काम के तुरंत बाद होने वाली "विशेषता docstrings" कहा जाता है।

तो निम्न माना जाता है प्रलेखित गुण:

class Foo(object): 
    velocity = 1 
    """Foo's initial velocity""" 

    def __init__(self, args): 
    self.location = 0.0 
    """Foo's initial location""" 

(संपादित करें: फिक्स्ड दूसरा docstring) मदद का उपयोग कर अजगर दुभाषिया में एक संपत्ति की

Answer 2

कक्षा डॉकस्ट्रिंग में दस्तावेज़ आसानी से सुलभ विशेषताओं या उन्हें गुणों में बनाते हैं। आप गुणों को सही तरीके से दस्तावेज कर रहे हैं, समस्या 2.x और पुरानी शैली की कक्षाओं में हो सकती है, जो वर्णनकर्ताओं का समर्थन नहीं करती - उस मामले में object से प्राप्त होती है।

Answer 3

Sphinx नोटेशन/Restructured Text आपके डॉकस्ट्रिंग में आप पाइथन स्रोतों से स्वचालित रूप से स्वरूपित दस्तावेज उत्पन्न कर सकते हैं। यह तर्कों का समर्थन करता है और कार्यों के लिए मान वापस करता है - जहां तक ​​मुझे पता है कि कोई फ़ील्ड नहीं है, लेकिन आप आसानी से उनके लिए एक सूची बना सकते हैं।

Answer 4

प्रलेखन मेरे लिए ठीक काम करता है, proprerty documentation देखते हैं। नोट: आईपीथॉन का जादू सहायता ऑपरेटर, ?, संपत्ति डॉकस्ट्रिंग प्रदर्शित नहीं करता है।

>>> class foo(object): 
>>> def __init__(self, bar): 
>>>  self._bar = bar 
>>> @property 
>>> def bar(self): 
>>>  """bar property""" 
>>>  return self._bar 
>>> help(foo.bar) 
Help on property: 

    bar property 

स्फिंक्स में आप गुण दस्तावेज़ के लिए :members: निर्देश का उपयोग करना चाहिए, autodoc documentation देखते हैं। मेरे लिए एक आकर्षण की तरह काम करता है!

विशेषताएँ स्पिंक्स द्वारा भी दस्तावेज की जाएगी यदि :members: का उपयोग किया जाता है। गुणों के लिए दस्तावेज़ों को विशेषता से पहले टिप्पणियों के रूप में दिया जा सकता है, लेकिन हैश चिह्न के बाद एक कोलन का उपयोग करके, ईजी #: the foo attribute।

मॉड्यूल डेटा के सदस्यों और वर्ग गुण के लिए, दस्तावेज़ीकरण या तो विशेष प्रारूपण वाले एक टिप्पणी में डाल दिया जा सकता है: स्फिंक्स autodoc प्रलेखन से (एक # का उपयोग कर: के बजाय सिर्फ # की टिप्पणी शुरू करने के लिए), या एक docstring में परिभाषा के बाद। टिप्पणियों को परिभाषा से पहले या एक ही पंक्ति पर असाइनमेंट के तुरंत बाद अपनी खुद की एक पंक्ति पर होना चाहिए। उत्तरार्द्ध रूप केवल एक पंक्ति तक ही सीमित है।