मैं अपनी टिप्पणी को उत्तर के रूप में दोहराता हूं क्योंकि मुझे ऐसा करने के लिए कहा गया था।
आम तौर पर उदाहरण (सार्वजनिक) विशेषताएं आत्म-व्याख्यात्मक होती हैं और उपयोगकर्ता द्वारा उनके उपयोग को दस्तावेज़ीकरण की आवश्यकता नहीं होती है। विशेषता और संदर्भ का नाम यह स्पष्ट करने के लिए पर्याप्त है कि विशेषता क्या है और आप कक्षा के दस्तावेज़ में इसे संभालने के तरीके के बारे में कुछ दस्तावेज जोड़ सकते हैं।
आप कुछ परिस्थितियों में समाप्त हो सकते हैं जिसमें आप उपयोगकर्ता को एक विशेषता का उपयोग प्रदान करना चाहते हैं लेकिन विशेषता स्वयं स्पष्टीकरणपूर्ण नहीं है और/या इसके हैंडलिंग को ध्यान देने की आवश्यकता है (क्योंकि अगर सही ढंग से संभाला नहीं जा सकता है तो यह " चीजें उड़ाना ")।
उदाहरण के लिए आप उपयोगकर्ता को यह जानना चाहेंगे कि किसी विशेषता में इसका उपयोग करने की अनुमति देने के लिए एक विशिष्ट "इंटरफ़ेस" होना चाहिए। या आपको ऐसी स्थिति की व्याख्या करनी है जिसे विशेषता द्वारा पूरा किया जाना चाहिए।
इस मामले में दस्तावेज को कक्षा के दस्तावेज़ के साथ एक साथ रखना अच्छा विचार नहीं है, क्योंकि कक्षा का दस्तावेज लंबा और लंबा हो जाता है और यह वास्तव में बहुत से विशिष्ट ज्ञान की व्याख्या करता है।
सरल और, मुझे लगता है कि, अधिक सुरुचिपूर्ण समाधान गुणों का उपयोग करना है। गुण आपको विशेषता और पर एक डॉकस्ट्रिंग जोड़ने देते हैं, जिससे आप वास्तव में उस पर पहुंच को नियंत्रित करने का एक तरीका देते हैं, इस प्रकार कक्षा को और अधिक मजबूत बनाने की अनुमति मिलती है।
यदि आपको बहुत से गुणों से निपटना है तो संपत्तियों के दसियों को लिखना परेशानी हो सकती है, लेकिन आप अभी भी गतिशील रूप से जोड़ सकते हैं, उदाहरण के लिए सजावट का उपयोग करना। यह अच्छी तरह से काम करता है, खासकर यदि आप हमेशा एक ही प्रकार के गेटर/सेटर का उपयोग करके एक डॉकस्ट्रिंग जोड़ना चाहते हैं।
उदाहरण के लिए आप लिख सकते हैं:
def set_properties(names_to_docs):
def decorator(cls):
for name, doc in names_to_docs.items():
prop = property((lambda self: getattr(self, '_{}'.format(name))),
(lambda self, val: setattr(self, '_{}'.format(name), val),
doc=doc)
setattr(cls, name, prop)
return cls
return decorator
और इस तरह इसका इस्तेमाल:
>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
... def __init__(self):
... self._a = 1
... self._b = 2
...
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1
एक टिप्पणी लुकास ग्रेफ ने बताया कि आप जो केवल एक वर्ग बनाने के लिए उपयोग कर सकते हैं Zope.interface में कंक्रीट क्लास का वर्णन करता है, जो आपको गुणों के लिए डॉकस्ट्रिंग जोड़ने का मौका देता है। यह शायद एक और विकल्प होगा। मुझे Zope.interface का उपयोग करने में अनुभव नहीं हुआ है, इसलिए मैं यह नहीं बता सकता कि आप क्या कर सकते हैं और कैसे, और अंततः ऑटो-प्रलेखन कार्यक्रमों के साथ कैसे इंटरैक्ट करते हैं।
यह सिर्फ मेरी विनम्र राय है, लेकिन यदि आप उन्हें स्वयं दस्तावेज तरीके से नामित करते हैं, खासकर अजगर के साथ आपको किसी और दस्तावेज की आवश्यकता नहीं है ... –
मैं @ जोरन बेस्ले से सहमत हूं, अगर मेरे कार्य/कक्षाएं काफी बड़ी हो जाती हैं व्यक्तिगत विशेषताओं को दस्तावेज़ीकरण की आवश्यकता होती है, वैसे भी कुछ मजाकिया लगता है। – Shep
मैं आमतौर पर उन्हें कक्षा दस्तावेज में दस्तावेज करता हूं। मुझे भी यह नहीं लगता कि उन्हें वास्तव में कुछ विशेष दस्तावेज़ की आवश्यकता होनी चाहिए। यदि आप दस्तावेज़ बनाना चाहते हैं कि कुछ चर को संभालने पर विशेष ध्यान देने की आवश्यकता है (उदा। एक निश्चित प्रकार होना चाहिए या किसी प्रकार का आविष्कार आदि होना चाहिए), तो आपको इसके लिए एक संपत्ति बनाना चाहिए। यह आपको न केवल दस्तावेज जोड़ने के लिए बल्कि आवश्यक नियंत्रणों को लागू करने की अनुमति देता है। – Bakuriu