परिवर्तनीय

Question

के लिए डॉकस्ट्रिंग क्या यह सादा चर के लिए डॉकस्ट्रिंग का उपयोग करने के लिए सकारात्मक है? उदाहरण के लिए मैं मॉड्यूल t

def f(): 
    """f""" 

l = lambda x: x 
"""l""" 

कहा जाता है और मैं

>>> import t 
>>> t.f.__doc__ 
'f' 

लेकिन

>>> t.l.__doc__ 
>>> 

उदाहरण PEP 258 के (के लिए "इस ग्राम है" खोज) के समान है है।

Answer 1

नहीं, यह संभव नहीं है और यदि आप कर सकते हैं तो यह उपयोगी नहीं होगा।

डॉकस्ट्रिंग हमेशा एक ऑब्जेक्ट (मॉड्यूल, कक्षा या फ़ंक्शन) का गुण होता है, जो विशिष्ट चर से बंधे नहीं होते हैं।

इसका मतलब है कि अगर आप सकता है कार्य करें:

t = 42 
t.__doc__ = "something" # this raises AttributeError: '__doc__' is read-only 

आप चर t के लिए पूर्णांक 42 नहीं के लिए दस्तावेज़ की स्थापना की जाएगी। जैसे ही आप t को रीबंड करते हैं, आप डॉकस्ट्रिंग खो देते हैं। अनियमित वस्तुओं जैसे तारों की संख्या कभी-कभी अलग-अलग उपयोगकर्ताओं के बीच साझा की गई एक वस्तु होती है, इसलिए इस उदाहरण में आप वास्तव में अपने कार्यक्रम में 42 के सभी अवसरों के लिए डॉकस्ट्रिंग सेट कर चुके हैं।

print(42 .__doc__) # would print "something" if the above worked! 

उत्परिवर्तनीय वस्तुओं के लिए यह आवश्यक रूप से हानिकारक नहीं होगा लेकिन यदि आप ऑब्जेक्ट को पुनर्निर्मित करते हैं तो भी सीमित उपयोग होगा।

यदि आप कक्षा की विशेषता दस्तावेज करना चाहते हैं तो इसका वर्णन करने के लिए कक्षा के डॉक्स्टिंग का उपयोग करें।

Answer 2

नहीं, आप केवल मॉड्यूल, (लैम्ब्डा और "सामान्य") कार्यों और कक्षाओं के लिए ऐसा कर सकते हैं, जहां तक ​​मुझे पता है। अन्य वस्तुओं, यहां तक ​​कि परिवर्तनशील वाले उनके वर्ग के docstrings वारिस और यदि आप उस बदलने की कोशिश AttributeError बढ़ा:।

>>> a = {} 
>>> a.__doc__ = "hello" 
Traceback (most recent call last): 
    File "<stdin>", line 1, in <module> 
AttributeError: 'dict' object attribute '__doc__' is read-only 

(आपका दूसरे उदाहरण वैध अजगर है, लेकिन स्ट्रिंग """l""" कुछ नहीं करता यह उत्पन्न होता है , मूल्यांकन और त्याग दिया गया।)

Answer 3

कुछ पायथन दस्तावेज़ स्क्रिप्ट्स में नोटेशन है जो मॉड्यूल/कक्षाओं में एक var दस्तावेज़ को दस्तावेज़ करने के लिए उपयोग किया जा सकता है।

उदा। स्पिनक्स के लिए, आप इसका उपयोग कर सकते हैं: var और: ivar। यह document देखें (लगभग आधे रास्ते नीचे)।

Answer 4

Epydoc docstrings on variables के लिए अनुमति देता है: भाषा सीधे उनके लिए प्रदान करता है नहीं है

, वहीं Epydoc चर docstrings समर्थन करता है: यदि किसी वैरिएबल असाइनमेंट बयान तुरंत एक नंगे स्ट्रिंग हो शाब्दिक, तो वह काम है उस चर के लिए एक डॉकस्ट्रिंग के रूप में माना जाता है।

उदाहरण:

class A: 
    x = 22 
    """Docstring for class variable A.x""" 

    def __init__(self, a): 
     self.y = a 
     """Docstring for instance variable A.y 

Answer 5

ठीक है, भले ही अजगर चर के लिए एक docstring के रूप में एक वैश्विक परिभाषा के तुरंत बाद परिभाषित तार का इलाज नहीं है, स्फिंक्स करता है और यह निश्चित रूप से एक बुरा व्यवहार उन्हें शामिल करने के लिए नहीं है ।

debug = False 
'''Set to True to turn on debugging mode. This enables opening IPython on 
exceptions. 
''' 

यहाँ कुछ कोड है कि एक मॉड्यूल को स्कैन और वैश्विक चर परिभाषाएँ, मूल्य और एक docstring कि इस प्रकार के नाम बाहर खींच जाएगा।

def GetVarDocs(fname): 
    '''Read the module referenced in fname (often <module>.__file__) and return a 
    dict with global variables, their value and the "docstring" that follows 
    the definition of the variable 
    ''' 
    import ast,os 
    fname = os.path.splitext(fname)[0]+'.py' # convert .pyc to .py 
    with open(fname, 'r') as f: 
     fstr = f.read() 
    d = {} 
    key = None 
    for node in ast.walk(ast.parse(fstr)): 
     if isinstance(node,ast.Assign): 
      key = node.targets[0].id 
      d[key] = [node.value.id,''] 
      continue 
     elif isinstance(node,ast.Expr) and key: 
      d[key][1] = node.value.s.strip() 
     key = None 
    return d 

Answer 6

Epydoc के बारे में फोर्ड के जवाब देने के लिए करने के लिए जोड़ने के लिए, ध्यान दें कि PyCharm ने भी प्रथम श्रेणी में एक चर के लिए एक स्ट्रिंग प्रलेखन के रूप में शाब्दिक का उपयोग करेगा:

class Fields_Obj: 
    DefaultValue=None 
    """Get/set the default value of the data field""" 

Answer 7

स्फिंक्स है एक के लिए निर्मित वाक्य रचना दस्तावेज़ों को दस्तावेज करना (यानी @ डंकन के रूप में मान नहीं)। उदाहरण:

#: This is module attribute 
x = 42 

class MyClass: 

    #: This is a class attribute 
    y = 43 

आप स्फिंक्स डॉक्स में अधिक पढ़ सकते हैं: http://www.sphinx-doc.org/en/1.4.8/ext/autodoc.html#directive-autoattribute

... या इस दूसरे प्रश्न में: How to document a module constant in Python?