एक बतख प्रकार को कैसे दस्तावेज़ित करें?

Question

मेरे पास प्रलेखन ब्लाउट है, क्योंकि जब भी मुझे एक जटिल बतख-प्रकार का सामना करना पड़ता है, मुझे "इस बतख के प्रकार" कहने के लिए कुछ तरीका चाहिए, लेकिन इसके बजाय "आपके फ़ंक्शन को इस इनपुट की आवश्यकता होती है, लेकिन यह दस्तावेज नहीं करता है ", और उसके बाद इसे दस्तावेज। यह जैसे कि निम्न, फूला हुआ, दोहराए दस्तावेज में परिणाम:

def Foo(arg): 
    """ 
    Args: 
     arg: An object that supports X functionality, and Y functionality, 
     and can be passed to Z other functionality. 
    """ 
    # Insert code here. 

def Bar(arg): 
    """ 
    Args: 
     arg: An object that supports X functionality, and Y functionality, 
     and can be passed to Z other functionality. 
    """ 
    # Insert code here. 

और इसी तरह, और इतने पर, Baz, Qux, और अन्य कार्यों के लिए। मुझे लिखने के कुछ छोटे तरीके की आवश्यकता है "arg एक (वस्तु का प्रकार) है"।

कुछ बतख प्रकारों के लिए, यह के रूप में "एक dict जैसी वस्तु 'के रूप में आसान है: हम जानते हैं कि हम एक dict की उम्मीद है, और इसलिए, हम क्या पारित करने के लिए पता है। एक dict, या ऐसा कुछ जो नकल कर सकता है।

मुझे लगता है कि सी ++ में टेम्पलेट प्रकारों के साथ एक ही समस्या है। हास्केल के पास यह होगा, लेकिन कोई इसे दस्तावेज करने के लिए एक प्रकार की कक्षा की परिभाषा का उपयोग कर सकता है। (नोट: हास्केल कक्षाएं! = जावा/सी ++/पायथन/आदि में कक्षाएं) (नोट: मैं वास्तव में हास्केल में प्रोग्राम नहीं करता हूं, इसलिए मुझे माफ कर दो अगर यह एक क्रोधित उदाहरण है।)

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

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

---

संपादित: जवाब के लिए: मुझे पता है कि बतख टाइपिंग है (उस पोस्ट से स्पष्ट होना चाहिए)। मैं कहां दस्तावेज करता हूं यह सवाल है, esp। जब दस्तावेज संलग्न करने के लिए कोई वर्ग मौजूद नहीं है।

Answer 1

बतख टाइपिंग के पीछे विचार यह आप दस्तावेज़ जिसे एक बतख की उम्मीद कर रहे हैं और यह नकली एक बतख होने के अन्य वस्तुओं पर निर्भर है है।

कहीं भी दस्तावेज़ में कोई एपीआई निर्दिष्ट नहीं करता है कि यह एक स्ट्रिंगियो ऑब्जेक्ट स्वीकार करता है। इसके बजाए, हम उन जगहों पर हैं जो फ़ाइल जैसी वस्तु की अपेक्षा करते हैं।

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

यदि आप इससे अधिक विशिष्ट होना चाहते हैं, तो आप abstract base classes इस्तेमाल कर सकते हैं। कई पहले से ही collections module (जैसे इटेरबल, हैशबल, और साइज्ड) या numbers module (तर्कसंगत, इंटीग्रल, आदि) में शामिल हैं। आपको लिखने के बाद मॉडल करना मुश्किल नहीं है। फिर, प्रलेखन बस का उल्लेख है जो एबीसी के लिए आवश्यक हैं (y एक Integral है अर्थात एक्स एक SizedIterable और है)।

Answer 2

बतख टाइपिंग की बात यह है कि "प्रकार" की धारणा एक सार सहज विचार हो जाता है, बल्कि कुछ औपचारिक रूप से भाषा का हिस्सा है कि तुलना में है। यह उन भाषाओं की तुलना में अधिक तरल पदार्थ और लचीला टाइपिंग करता है जहां टाइपिंग चेकिंग भाषा का हिस्सा है।

जब बतख टाइपिंग का उपयोग कर क्या आवश्यक है कि कार्यक्रम जानता है क्या "प्रकार" आप उपयोग कर रहे हैं, लेकिन वह अन्य प्रोग्रामर करना नहीं है। तो यदि आपके पास कक्षाओं/कार्यों/आदि का एक पूरा परिवार है जो किसी विशेष "प्रकार" की वस्तुओं पर काम करता है, और उस प्रकार को कुछ शब्दों में वर्णित करने में सक्षम नहीं है, तो टिप्पणियों या डॉकस्ट्रिंग में एक अनुभाग जोड़ें (या यहां तक ​​कि एक बाहरी .txt फ़ाइल) आपके प्रकार का वर्णन और नामकरण। फिर आप बस उस नाम को हर जगह देख सकते हैं।

Answer 3

जावा जैसी अधिक सख्ती से टाइप की गई भाषाओं में "इंटरफेस" की अवधारणा है: इंटरफ़ेस को लागू करने वाली किसी भी कक्षा को विधियों के संग्रह प्रदान करना चाहिए।

मुझे लगता है आप जरूरी सख्त टाइपिंग के सामान के साथ लाए बिना अवधारणा उधार ले सकता: बस को परिभाषित करने और एक अमूर्त वर्ग Foo दस्तावेज़, और फिर कहते हैं कि अपने विधि उम्मीद "एक Foo या एक Foo की तरह वस्तु"। यदि आप नहीं चाहते हैं तो आपको किसी अन्य वर्ग को वास्तव में Foo से प्राप्त करने की आवश्यकता नहीं है; दस्तावेज़ों को पढ़ने वाले लोग अब भी पता चलेगा कि Foo-ऑब्जेक्ट की तरह क्या अपेक्षा की जाती है।