जवाबों:
पहले रूप को जावदोक कहा जाता है । जब आप अपने कोड के लिए औपचारिक एपीआई लिख रहे हों, जो javadocउपकरण द्वारा उत्पन्न किया जाता है, तो आप इसका उपयोग करते हैं । एक उदाहरण के लिए, जावा 7 एपीआई पेज Javadoc का उपयोग करता है और उस उपकरण द्वारा उत्पन्न किया गया था।
Javadoc में आपके द्वारा देखे जाने वाले कुछ सामान्य तत्व शामिल हैं:
@param: इसका उपयोग यह इंगित करने के लिए किया जाता है कि किसी विधि को क्या पैरामीटर पास किया जा रहा है, और उनके पास क्या मूल्य है
@return: इसका उपयोग यह इंगित करने के लिए किया जाता है कि विधि किस परिणाम को वापस देने जा रही है
@throws: यह इंगित करने के लिए उपयोग किया जाता है कि एक विधि कुछ इनपुट के मामले में एक अपवाद या त्रुटि फेंकता है
@since: इसका उपयोग इस वर्ग या कार्य में उपलब्ध जल्द से जल्द जावा संस्करण को इंगित करने के लिए किया जाता है
एक उदाहरण के रूप में, यहाँ की compareविधि के लिए Javadoc Integer:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}दूसरा रूप एक ब्लॉक (मल्टी-लाइन) टिप्पणी है। यदि आप एक टिप्पणी में कई लाइनें रखना चाहते हैं तो आप इसका उपयोग करते हैं।
मैं कहता हूँ कि आप केवल उत्तरार्द्ध फार्म का उपयोग करना चाहते हैं किफ़ायत से ; यही है, आप अपने कोड को ब्लॉक टिप्पणियों के साथ ओवरबर्ड नहीं करना चाहते हैं जो यह वर्णन नहीं करते हैं कि विधि / जटिल फ़ंक्शन का क्या व्यवहार है।
चूँकि Javadoc दो में से अधिक वर्णनात्मक है, और आप इसका उपयोग करने के परिणामस्वरूप वास्तविक प्रलेखन उत्पन्न कर सकते हैं, Javadoc का उपयोग करना सरल ब्लॉक टिप्पणियों के लिए अधिक बेहतर होगा।
जावा प्रोग्रामिंग भाषा के लिए , दोनों के बीच कोई अंतर नहीं है । जावा में दो प्रकार की टिप्पणियाँ हैं: पारंपरिक टिप्पणियाँ ( /* ... */) और अंत-पंक्ति टिप्पणियाँ ( // ...)। जावा लैंग्वेज स्पेसिफिकेशन देखें । तो, जावा प्रोग्रामिंग भाषा के लिए, दोनों /* ... */और /** ... */पारंपरिक टिप्पणियों के उदाहरण हैं, और वे दोनों जावा संकलक द्वारा ठीक उसी व्यवहार कर रहे हैं, यानी, वे अनदेखी कर रहे हैं (या अधिक सही ढंग से: वे सफेद स्थान माना जाता है)।
हालाँकि, जावा प्रोग्रामर के रूप में, आप केवल जावा कंपाइलर का उपयोग नहीं करते हैं। आप एक संपूर्ण उपकरण श्रृंखला का उपयोग करते हैं, जिसमें संकलक, एक आईडीई, एक निर्माण प्रणाली, आदि शामिल हैं और इनमें से कुछ उपकरण जावा संकलक की तुलना में चीजों को अलग तरीके से व्याख्या करते हैं। विशेष रूप से, /** ... */टिप्पणियों की व्याख्या Javadoc टूल द्वारा की जाती है, जो जावा प्लेटफ़ॉर्म में शामिल है और प्रलेखन उत्पन्न करता है। जावाडॉक उपकरण जावा स्रोत फ़ाइल को स्कैन करेगा और /** ... */प्रलेखन के बीच के हिस्सों की व्याख्या करेगा ।
यह टैगों के समान है FIXMEऔर TODO: यदि आप जैसी टिप्पणी शामिल करते हैं // TODO: fix thisया // FIXME: do that, अधिकांश आईडीई ऐसी टिप्पणियों को उजागर करेंगे ताकि आप उनके बारे में न भूलें। लेकिन जावा के लिए, वे सिर्फ टिप्पणियां हैं।
javadocउपकरण कुछ व्याख्या नहीं कर सकता है।
JLS की धारा 3.7 को अच्छी तरह से पढ़ना आपको जावा में टिप्पणियों के बारे में जानने की जरूरत है।
टिप्पणी के दो प्रकार हैं:
- / * पाठ * /
एक पारंपरिक टिप्पणी: ASCII वर्णों के सभी पाठ / * से ASCII वर्णों * को अनदेखा किया जाता है (जैसा कि C और C ++ में है)।
- // पाठ
एक अंत-पंक्ति की टिप्पणी: पंक्ति के अंत तक ASCII वर्ण // से सभी पाठ को अनदेखा किया जाता है (जैसा कि C ++ में)।
आपके प्रश्न के बारे में,
पहले वाला
/**
*
*/Javadoc Technology घोषित करने के लिए उपयोग किया जाता है ।
Javadoc एक उपकरण है जो स्रोत फ़ाइलों के एक सेट में घोषणाओं और प्रलेखन टिप्पणियों को पार्स करता है और कक्षाओं, इंटरफेस, निर्माणकर्ताओं, विधियों और क्षेत्रों का वर्णन करते हुए HTML पृष्ठों का एक सेट तैयार करता है। Javadoc आउटपुट को कस्टमाइज़ करने के लिए आप Javadoc डॉकलेट का उपयोग कर सकते हैं। एक डॉकलेट एक प्रोग्राम है जो डॉकलेट एपीआई के साथ लिखा जाता है जो टूल द्वारा उत्पन्न की जाने वाली आउटपुट की सामग्री और प्रारूप को निर्दिष्ट करता है। आप HTML, SGML, XML, RTF और MIF जैसे किसी भी प्रकार के टेक्स्ट फ़ाइल आउटपुट को उत्पन्न करने के लिए एक डॉकलेट लिख सकते हैं। ओरेकल HTML- प्रारूप एपीआई प्रलेखन उत्पन्न करने के लिए एक मानक डॉकलेट प्रदान करता है। Doclets का उपयोग एपीआई प्रलेखन के उत्पादन से संबंधित विशेष कार्य करने के लिए भी किया जा सकता है।
एपीआई केDoclet संदर्भ में अधिक जानकारी के लिए ।
दूसरा, जैसा कि जेएलएस में स्पष्ट रूप से समझाया गया है, के बीच के सभी पाठों को अनदेखा कर देगा /*और */इस प्रकार बहुस्तरीय टिप्पणियां बनाने के लिए उपयोग किया जाता है।
कुछ अन्य बातें जो आप जावा में टिप्पणियों के बारे में जानना चाहते हैं
/* and */ उन टिप्पणियों में कोई विशेष अर्थ नहीं है जो इसके साथ शुरू होती हैं // ।// उन टिप्पणियों में कोई विशेष अर्थ नहीं है जो इसके साथ शुरू होती हैं /* or /** ।इस प्रकार, निम्नलिखित पाठ एक पूर्ण टिप्पणी है:
/* this comment /* // /** ends here: */मुझे नहीं लगता कि मौजूदा उत्तरों ने प्रश्न के इस हिस्से को पर्याप्त रूप से संबोधित किया है:
मुझे उनका उपयोग कब करना चाहिए?
यदि आप एक एपीआई लिख रहे हैं जो आपके संगठन के भीतर प्रकाशित या पुन: उपयोग किया जाएगा, तो आपको हर publicवर्ग, विधि और क्षेत्र के साथ-साथ protectedगैर- finalवर्गों के तरीकों और क्षेत्रों के लिए व्यापक Javadoc टिप्पणियां लिखनी चाहिए । Javadoc को उन सभी चीज़ों को कवर करना चाहिए जिन्हें विधि हस्ताक्षर द्वारा सूचित नहीं किया जा सकता है, जैसे कि पूर्व शर्त, पोस्टकंडिशन, मान्य तर्क, रनटाइम अपवाद, आंतरिक कॉल, आदि।
यदि आप एक आंतरिक एपीआई (एक ही प्रोग्राम के विभिन्न हिस्सों द्वारा उपयोग किया जाता है) लिख रहे हैं, तो Javadoc यकीनन कम महत्वपूर्ण है। लेकिन रखरखाव प्रोग्रामर के लाभ के लिए, आपको अभी भी किसी भी विधि या क्षेत्र के लिए Javadoc लिखना चाहिए जहां सही उपयोग या अर्थ तुरंत स्पष्ट नहीं है।
जावदोक की "हत्यारा विशेषता" यह है कि यह ग्रहण और अन्य आईडीई के साथ निकटता से जुड़ा हुआ है। एक डेवलपर को अपने माउस पॉइंटर को केवल एक पहचानकर्ता पर हॉवर करने की आवश्यकता होती है, ताकि वे इसके बारे में जानने के लिए आवश्यक हर चीज को जान सकें। लगातार प्रलेखन का जिक्र अनुभवी जावा डेवलपर्स के लिए दूसरी प्रकृति बन जाता है, जो अपने स्वयं के कोड की गुणवत्ता में सुधार करता है। यदि आपका API Javadoc के साथ प्रलेखित नहीं है, तो अनुभवी डेवलपर्स इसका उपयोग नहीं करना चाहेंगे।
जावा कोड की निम्न सूची में टिप्पणियां ग्रेयर्ड आउट वर्ण हैं:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}जावा भाषा तीन प्रकार की टिप्पणियों का समर्थन करती है:
/* text */संकलक सब कुछ से अनदेखा करता /*है */।
/** documentation */यह एक दस्तावेजी टिप्पणी (संक्षिप्त टिप्पणी, लघु के लिए) इंगित करता है। कंपाइलर इस तरह की टिप्पणी को अनदेखा करता है, ठीक उसी तरह जैसे वह टिप्पणियों का उपयोग करता है /*और */। JDK javadoc टूल स्वचालित रूप से जनरेट किए गए दस्तावेज़ तैयार करते समय डॉक्टर टिप्पणियों का उपयोग करता है।
// textकंपाइलर //लाइन के अंत से सब कुछ अनदेखा करता है ।
अब के बारे में जब आप उन्हें इस्तेमाल किया जाना चाहिए:
// textजब आप कोड की एक पंक्ति पर टिप्पणी करना चाहते हैं, तब उपयोग करें ।
उपयोग /* text */जब आप कोड की कई पंक्तियों पर टिप्पणी करना चाहें, तब ।
उपयोग करें /** documentation */ जब आप प्रोग्राम के बारे में कुछ जानकारी जोड़ना चाहते हैं जो प्रोग्राम प्रलेखन के स्वचालित पीढ़ी के लिए उपयोग किया जा सकता है।
पहले एक जावदोक के लिए है जिसे आप कक्षाओं, इंटरफेस, विधियों आदि के शीर्ष पर परिभाषित करते हैं। आप जावदोक का उपयोग कर सकते हैं, जैसा कि नाम से पता चलता है कि कक्षा क्या करती है या किस विधि से अपना कोड दर्ज करती है और इस पर रिपोर्ट तैयार करती है।
दूसरा एक कोड ब्लॉक कमेंट है। उदाहरण के लिए कहें कि आपके पास कुछ कोड ब्लॉक हैं जो आप नहीं चाहते हैं कि कंपाइलर व्याख्या करें तो आप कोड ब्लॉक टिप्पणी का उपयोग करें।
एक और // यह आप कथन स्तर पर उपयोग करते हैं यह निर्दिष्ट करने के लिए कि कोड की कार्यवाही लाइनें क्या करने वाली हैं।
कुछ अन्य भी हैं जैसे // TODO, यह चिह्नित करेगा कि आप उस स्थान पर बाद में कुछ करना चाहते हैं
// FIXME आप तब उपयोग कर सकते हैं जब आपके पास कुछ अस्थायी समाधान हो लेकिन आप बाद में यात्रा करना चाहते हैं और इसे बेहतर बनाना चाहते हैं।
उम्मीद है की यह मदद करेगा
जावा दो प्रकार की टिप्पणियों का समर्थन करता है:
/* multiline comment */: संकलक सब कुछ से अनदेखा करता /*है */। टिप्पणी कई लाइनों पर हो सकती है।
// single line: संकलक //लाइन के अंत से सब कुछ अनदेखा करता है ।
कुछ उपकरण जैसे कि जावाडॉक अपने उद्देश्य के लिए एक विशेष बहुस्तरीय टिप्पणी का उपयोग करते हैं। उदाहरण के लिए /** doc comment */javadoc द्वारा उपयोग की जाने वाली एक दस्तावेजी टिप्पणी है जो स्वचालित रूप से उत्पन्न दस्तावेज तैयार करते हैं, लेकिन जावा के लिए यह एक सरल बहुभाषी टिप्पणी है।
/** .. */सिर्फ एक नियमित रूप से बहुस्तरीय टिप्पणी है, और इसके भीतर पहला चरित्र तारांकन होता है।