@See और @inheritDoc के बीच अंतर का विवरण

Question

मैंने JavaDoc संदर्भ पर ध्यान दिया है , और जब मैं @see(विभिन्न लिंक) और {@inheritDoc}(सुपरक्लास जावाडॉक टिप्पणी का निर्यात ) के बीच बुनियादी अंतर को समझता हूं, तो मुझे इस बात पर स्पष्टीकरण की आवश्यकता है कि वास्तव में कैसे चीजें लागू की गईं।

ग्रहण आईडीई में जब मैं विरासत में मिली विधि के लिए "जनरेट एलीमेंट कमेंट्स" का चयन करता हूं (इंटरफेस से, या स्ट्रींग () ओवरराइड, और इसके बाद) यह निम्नलिखित टिप्पणी बनाता है

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

अगर मैं JavaDoc उत्पादन करने के लिए आवश्यक कर रहा हूँ मुझे लगता है कि इसे वैसे ही रखते, की जगह @seeके साथ {@inheritDoc}, या उसमें सदाशयी जैसे JavaDoc:

/**
 * {@inheritDoc}
 */

और जब मैं ऐसा करूं, तब भी क्या मुझे क्लास # मेथड फ्लैग रखना चाहिए?

Answer 1

सबसे पहले, आपको मूल ग्रहण टेम्पलेट को हटा देना चाहिए क्योंकि यह सिर्फ शोर रद्दी है। या तो सार्थक डॉक्स लगाएं या कुछ भी न डालें। लेकिन आईडीई टेम्प्लेट का उपयोग करके स्पष्ट रूप से बेकार की पुन: स्थापना कोड को पूरी तरह से बंद कर देती है।

दूसरा, यदि आपको javadoc का उत्पादन करने की आवश्यकता है, तो आपको टिप्पणी के साथ शुरुआत करनी होगी /**। अन्यथा, यह javadoc नहीं है।

अंत में, यदि आप ओवरराइड कर रहे हैं, तो आपको उपयोग करना चाहिए @inheritDoc(यह मानते हुए कि आप मूल डॉक्स में जोड़ना चाहते हैं , जैसा कि @seh ने एक टिप्पणी में उल्लेख किया है, यदि आप मूल डॉक्स की नकल करना चाहते हैं, तो आपको कुछ भी करने की आवश्यकता नहीं है)। @seeकेवल वास्तव में अन्य संबंधित तरीकों को संदर्भित करने के लिए उपयोग किया जाना चाहिए ।

Comments

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

— सेह

मैंने डॉक्स जनरेट किया और उसके बिना @inheritDocऔर किसी भी तरह का अंतर नहीं देखा। यहां तक ​​कि बिना @inheritDoc, मैं देखता हूं कि व्युत्पन्न वर्ग के जावदोक को आधार वर्ग में जोड़ा गया था।

— randominstanceOfLivingThing

मैं यहां आया था क्योंकि चेकस्टाइल शिकायत करती है कि "विधि के विस्तार के लिए डिज़ाइन नहीं किया गया है"। एक अच्छा विचार उपयोग करने @inheritDocऔर फिर कुछ कार्यान्वयन विशिष्ट प्रलेखन जोड़ने के लिए हो सकता है , जैसे कि यह कैसे लागू करता है / मूल विधि को अधिलेखित करता है, और विशेष रूप से यह इसे जिस तरह से करता है।

— बेन