अजगर मॉड्यूल डॉकस्ट्रिंग में क्या रखा जाए? [बन्द है]

Question

ठीक है, इसलिए मैंने पीईपी 8 और पीईपी 257 दोनों को पढ़ा है , और मैंने फ़ंक्शन और कक्षाओं के लिए बहुत सारे डॉकस्ट्रिंग्स लिखे हैं, लेकिन मॉड्यूल डॉकस्ट्रिंग में क्या जाना चाहिए, इसके बारे में मैं थोड़ा अनिश्चित हूं। मुझे लगा कि कम से कम, यह उन फ़ंक्शन और क्लासेस को दस्तावेज़ित करना चाहिए जो मॉड्यूल निर्यात करता है, लेकिन मैंने कुछ मॉड्यूल भी देखे हैं जो लेखक के नाम, कॉपीराइट जानकारी आदि को सूचीबद्ध करते हैं। क्या किसी के पास एक अच्छा अजगर डॉकस्ट्रिंग कैसे होना चाहिए, इसका उदाहरण है संरचित हो?

Answer 1

help(yourmodule)इंटरएक्टिव इंटरप्रेटर के प्रॉम्प्ट पर किसी के बारे में सोचें - वे क्या जानना चाहते हैं? (जानकारी निकालने और प्रदर्शित करने के अन्य तरीके सूचना helpकी मात्रा के मामले में लगभग बराबर हैं)। तो अगर आप में है x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

फिर:

>>> import x; help(x)

दिखाता है:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

जैसा कि आप देख रहे हैं, वर्गों पर विस्तृत जानकारी (और फ़ंक्शंस भी, हालांकि मैं यहां एक नहीं दिखा रहा हूं) पहले से ही उन घटकों के डाइस्ट्रिंग से शामिल है; मॉड्यूल के स्वयं के डॉकस्ट्रिंग ने उन्हें बहुत संक्षेप में वर्णित किया है (यदि सभी पर) और बल्कि एक संक्षिप्त सारांश पर ध्यान केंद्रित करें कि समग्र रूप से मॉड्यूल आपके लिए क्या कर सकता है, आदर्श रूप से कुछ सिद्धांतित उदाहरणों के साथ (जैसे फ़ंक्शन और कक्षाएं आदर्श रूप में आदर्श उदाहरण हैं) उनकी डॉकस्ट्रिंग)।

मैं यह नहीं देखता कि मेटाडेटा जैसे कि लेखक का नाम और कॉपीराइट / लाइसेंस मॉड्यूल के उपयोगकर्ता को कैसे मदद करता है - यह टिप्पणी में जा सकता है, क्योंकि यह किसी व्यक्ति पर विचार कर सकता है कि क्या मॉड्यूल का पुन: उपयोग या संशोधित करना है या नहीं।

Comments

तो, क्या यह मॉड्यूल के शीर्ष पर टिप्पणियों में लेखक, कॉपीराइट आदि को शामिल करने के लिए प्रथागत है?

@ 007brendan, यह बहुत आम बात है, हाँ।

— एलेक्स मार्टेली

@IfLoop मुझे संदेह है कि उपयोगकर्ता help()की तुलना में दुभाषिया में विधि का उपयोग करने वाले अधिक उपयोगकर्ता हैं जो केवल कोड पढ़ते हैं।

— भ्रमित

ध्यान में रखना, दस्तावेज़ के लिए सबसे महत्वपूर्ण बात क्यों है । दस्तावेज जो कुछ करता है वह अच्छी तरह से लिखित कोड का काम है। दस्तावेज़ीकरण क्यों दस्तावेज़ीकरण का काम है।

— एरिक एरोनेस्टी

Answer 2

विनिर्देशों को उद्धृत करने के लिए :

स्क्रिप्ट (एक स्टैंड-अलोन प्रोग्राम) का डॉकस्ट्रिंग अपने "उपयोग" संदेश के रूप में उपयोग करने योग्य होना चाहिए, जब स्क्रिप्ट गलत या लापता तर्कों (या "-एच" विकल्प के साथ, "मदद" के लिए) के साथ लागू किया जाता है। इस तरह के एक डॉकस्ट्रिंग को स्क्रिप्ट के फ़ंक्शन और कमांड लाइन सिंटैक्स, पर्यावरण चर, और फ़ाइलों का दस्तावेज़ करना चाहिए। उपयोग संदेश काफी विस्तृत हो सकते हैं (कई स्क्रीन पूर्ण) और नए उपयोगकर्ता के लिए कमांड का सही उपयोग करने के लिए पर्याप्त होना चाहिए, साथ ही परिष्कृत उपयोगकर्ता के लिए सभी विकल्पों और तर्कों का पूरा त्वरित संदर्भ होना चाहिए।

मॉड्यूल के लिए docstring को आम तौर पर मॉड्यूल द्वारा निर्यात की जाने वाली कक्षाओं, अपवादों और कार्यों (और किसी भी अन्य वस्तुओं) को सूचीबद्ध करना चाहिए, प्रत्येक के एक-पंक्ति सारांश के साथ। (ये सारांश आम तौर पर ऑब्जेक्ट के डॉकस्ट्रिंग में सारांश रेखा की तुलना में कम विवरण देते हैं।) एक पैकेज के लिए डॉकस्ट्रिंग (यानी, पैकेज के __init__.pyमॉड्यूल के डॉकस्ट्रिंग ) को पैकेज द्वारा निर्यात किए गए मॉड्यूल और उपपैकेज को भी सूचीबद्ध करना चाहिए।

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

किसी फ़ंक्शन या विधि का डॉकस्ट्रिंग एक अवधि में समाप्त होने वाला वाक्यांश है। यह एक कमांड के रूप में फ़ंक्शन या विधि के प्रभाव को निर्धारित करता है ("ऐसा करें", "वापस लौटें"), विवरण के रूप में नहीं; उदाहरण के लिए "पथ नाम नहीं देता ..." लिखें। किसी फ़ंक्शन या विधि के लिए एक बहुस्तरीय-डॉकस्ट्रिंग को अपने व्यवहार को संक्षेप में प्रस्तुत करना चाहिए और अपने तर्कों, रिटर्न वैल्यू (साइड्स), साइड इफेक्ट्स, उठाए गए अपवादों, और प्रतिबंधों पर दस्तावेज़ करना चाहिए, जब इसे कहा जा सकता है (सभी यदि लागू हो)। वैकल्पिक तर्कों को इंगित किया जाना चाहिए। यह प्रलेखित किया जाना चाहिए कि क्या कीवर्ड तर्क इंटरफ़ेस का हिस्सा हैं।