अर्थपूर्ण डॉकस्ट्रिंग कैसे लिखें?

Question

आपकी राय में एक सार्थक डॉकस्ट्रिंग क्या है? आप वहां क्या वर्णन करने की उम्मीद करते हैं?

उदाहरण के लिए, पर विचार यह अजगर वर्ग के __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"): 
    """ 
    name - field name 
    value - field value 
    displayName - nice display name, if empty will be set to field name 
    matchingRule - I have no idea what this does, set to strict by default 
    """ 

आप इस सार्थक पाते हैं? सभी को जानने के लिए अपने अच्छे/बुरे उदाहरण पोस्ट करें (और एक सामान्य उत्तर ताकि इसे स्वीकार किया जा सके)।

Answer 1

मैं "कुछ भी जो आप विधि के हस्ताक्षर से नहीं बता सकते" से सहमत हैं। यह समझाने का भी अर्थ हो सकता है कि विधि/फ़ंक्शन क्या देता है।

आप अपने डॉकस्ट्रिंग के अंदर दस्तावेज़ उद्देश्यों के लिए Sphinx (और पुन: संरचित पाठ वाक्यविन्यास) का भी उपयोग करना चाह सकते हैं। इस तरह आप इसे आसानी से अपने दस्तावेज़ में शामिल कर सकते हैं। उदाहरण के लिए चेक आउट करें उदा। repoze.bfg जो इस व्यापक रूप से उपयोग करता है (example file, documentation example)।

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

Answer 2

वहाँ क्या जाना चाहिए:

कुछ भी है कि आप विधि के हस्ताक्षर से नहीं बता सकता। इस मामले में केवल थोड़ा उपयोगी है: displayName - यदि खाली है तो फ़ील्ड नाम पर सेट किया जाएगा।

Answer 3

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

Answer 4

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

एक अन्य उपयोगी चीज जिसे आप अपने डॉकस्ट्रिंग में डाल सकते हैं वह doctest है।

Answer 5

PEP 8 से:

अच्छा प्रलेखन तार (यानी "docstrings") लिखने के लिए सम्मेलनों PEP 257 में अमर कर रहे हैं।

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

Answer 6

बाहर चेक numpy के docstrings (जैसे http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py)।

docstrings विभाजित हैं कई वर्गों में और इस तरह दिखेगा:

Compute the sum of the elements of a list. 

Parameters 
---------- 
foo: sequence of ints 
    The list of integers to sum up. 

Returns 
------- 
res: int 
    sum of elements of foo 

See also 
-------- 
cumsum: compute cumulative sum of elemenents 

Answer 7

समारोह की शुरुआत में जोड़ने डॉक स्ट्रिंग जोड़ने की आम तौर पर उद्देश्य समारोह का वर्णन करने के लिए है, यह क्या करता है, wha यह वापस आ जाएगा, और पैरामीटर के बारे में विवरण। यदि आवश्यक हो तो आप कार्यान्वयन विवरण जोड़ सकते हैं। यहां तक ​​कि आप लेखक के बारे में विवरण भी जोड़ सकते हैं जिन्होंने भावी डेवलपर के लिए कोड लिखा था।