JavaDoc में @see का उपयोग?

110

@seeJavaDocs से निपटने के लिए मैं कब उपयोग करूं ? इसका क्या उपयोग है?

उदाहरण के लिए यदि MethodAकॉल करता है MethodBतो क्या मुझे 'javadoc' और 'संदर्भ' @seeमें डालना है क्योंकि इसे क्या कहा जाता है, या क्या मुझे इसका संदर्भ देना है क्योंकि यह इसे कॉल कर रहा है। मैंने ओरेकल वेबसाइट पर इसके बारे में सामान पढ़ा है और यह मुझे अविश्वसनीय रूप से अस्पष्ट लगता है, यह कहता है कि इसका अर्थ "देखें" भी है लेकिन वास्तव में इसका मतलब नहीं है!MethodBMethodAMethodBMethodA@see

java methods javadoc

— जेफ
स्रोत

4

javadoc और संदर्भ @seeमें डाल दिया गया है, क्योंकि इसे क्या कहा जाता हैMethodBMethodA -> कैसे संभव हो सकता है उन सभी तरीकों को जानना जो आपके किसी एक तरीके को कहते हैं? भले ही यह संभव हो (केवल एक बार इस्तेमाल की जाने वाली एक निजी विधि कहो) कैली से कॉलर की आवाज़ को जोड़ने पर कम से कम अजीब लगता है ...

— Mr_and_Mrs_D

1

इसका मतलब है कि आम तौर पर अंग्रेजी में इसका मतलब होता है: oxfordd शब्दकोशों.com / us /definition / american_english / see (परिभाषा 1.4)

— stackexchanger

119

हाँ, यह काफी अस्पष्ट है।

जब भी आपकी विधि के दस्तावेज़ीकरण के पाठकों के लिए इसका उपयोग करना चाहिए तो यह किसी अन्य विधि को देखने के लिए भी उपयोगी हो सकता है। यदि आपके मेथड के प्रलेखन में कहा गया है कि "मेथड बी की तरह काम करता है लेकिन ...", तो आपको निश्चित रूप से एक लिंक डालना चाहिए। @seeइनलाइन {@link ...}टैग का विकल्प होगा :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

जब तथ्य यह है कि मेथडए मेथडब को कॉल करता है तो कार्यान्वयन डिटेल है और बाहर से कोई वास्तविक संबंध नहीं है, आपको यहां लिंक की आवश्यकता नहीं है।

— पाओलो एबरमन
स्रोत

13

@seeविकल्प के @Deprecatedतरीकों से जोड़ने के लिए भी उपयोगी है ।

— मौवे रेंजर

1

@ माउवेरांगर चूंकि @seeबहुत अस्पष्ट है, पदावनत सामान के लिए मुझे कुछ अधिक स्पष्ट करने के लिए अधिक उपयोगी लगता है, जैसे:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— क्रिस्टोफर

10

एपीआई में संबंधित तरीकों / कक्षाओं की जानकारी के लिए @ डॉट उपयोगी है। यह प्रलेखन पर संदर्भित विधि / कोड के लिए एक लिंक का उत्पादन करेगा। जब संबंधित कोड हो तो इसका उपयोग करें जिससे उपयोगकर्ता को यह समझने में मदद मिल सके कि एपीआई का उपयोग कैसे किया जाए।

— रॉब डॉसन
स्रोत

9

एक स्थिति का एक अच्छा उदाहरण जब @seeउपयोगी हो सकता है एक इंटरफ़ेस / अमूर्त वर्ग विधि को लागू करना या ओवरराइड करना होगा। घोषणापत्र javadocमें विधि का विस्तार करने वाला खंड होगा और ओवरराइड / कार्यान्वित विधि एक @seeटैग का उपयोग कर सकती है , जो आधार एक का उल्लेख करती है।

संबंधित प्रश्न: @ के साथ उचित javadoc लिखना?

जावा एसई प्रलेखन: @see

— AtomHeartFather
स्रोत

2

मैं नहीं था, लेकिन यह शायद इसलिए था क्योंकि हमारे पास @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

@ के लिए जावा प्रलेखन वास्तव में अच्छा है। पहले होना चाहिए।

— dok

2

@vaxquis @inheritDocकिसी अन्य स्थान से दस्तावेज़ की प्रतिलिपि बनाता है। मुझे लगता है कि फुल जोड़ने के बजाय विवरण का वर्णन इसके उपयोग हैं?

— नील्सव

@ नील्सग ने इस उत्तर का उल्लेख किया है कि the overridden/implemented method could use a @see tag, referring to the base one.- और यह वास्तव में @inheritDocऐसा ही है; IMO बेहतर है कि बेस क्लास डिस्क्रिप्शन वर्बेटिम को इसके माध्यम से शामिल करें @inheritDoc और इसे आवश्यकतानुसार सप्लीमेंट करें, इसे देखें @see- देखें (sic!) Stackoverflow.com/questions/11121600/… ; कई डेवलपर्स (मुझे शामिल किया गया) एक अनुवर्ती पदानुक्रम के माध्यम से ऊपर की ओर जाने वाले लिंक के ऊपर की ओर झुकते हुए श्रृंखला के बजाय सभी कार्यान्वयन विवरणों को एक स्थान पर रखना पसंद करते हैं।

2

मैं एक इंटरफ़ेस कार्यान्वयन वर्ग के तरीकों को एनोटेट करने के लिए @ का उपयोग करता हूं जहां इंटरफ़ेस के javadoc में पहले से ही विधि का विवरण प्रदान किया गया है। जब हम करते हैं कि मैं नोटिस करता हूं कि ग्रहण तब भी इंटरफ़ेस के प्रलेखन को ऊपर खींचता है, जब मैं कोड के पूरा होने के दौरान कार्यान्वयन संदर्भ पर विधि खोज रहा हूं

— मारुथी
स्रोत