जावाडोक इंटरफ़ेस टिप्पणियां

Question

मेरे पास एक इंटरफ़ेस ए है जिसमें विधियों x, y और z हैं।

/** 
* 
* A.java 
* Interface class that has the following methods. 
* 
* @author MyName 
* @since mm-dd-yyyy 
*/ 

public interface A { 

    //method description for x 
    void x(); 

    //method description for y 
    void y(); 

    //method description for z 
    void z(); 
} 

यह सही है या मैं कक्षा टिप्पणियां करने के लिए अन्य बातों के जोड़ने चाहिए: मैं वर्ग इस तरह से टिप्पणी कर रहा हूँ?

Answer 1

हां आपको इंटरफ़ेस के पीछे प्रेरणा को स्पष्ट रूप से विशिष्ट करने के लिए उचित रूप से जवाडोक टिप्पणियां लिखनी चाहिए और दोनों कॉलर्स और कार्यान्वयनकर्ताओं के लिए अनुबंध क्या है।

उदाहरण के लिए JDK कोड में इंटरफेस में से कुछ पर एक नजर डालें, java.util.List

Answer 2

नहीं, आपने विधियों के लिए कोई भी जावाडॉक टिप्पणियां निर्दिष्ट नहीं की हैं। इंटरफ़ेस का उपयोग करने या कार्यान्वित करने वाला कोई व्यक्ति यह जानना चाहता है कि विधियों का क्या अर्थ है? आप उचित JavaDoc विवरण का उपयोग करना चाहिए: कॉल करने और इसको लागू करने: यह है कि ज्यादातर JavaDoc जो कॉल के उद्देश्य से है के विपरीत मन में

/** 
* This method fromulgates the wibble-wrangler. It should not be called without 
* first saturating all glashnashers. 
*/ 
void x(); 

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

संपादित कठिन है।

• व्यक्तिगत तौर पर मैं, @author टैग से छुटकारा पाने चाहते हैं के रूप में यह IMO शायद ही कभी उपयोगी है (आमतौर पर स्रोत नियंत्रण में देख और अधिक उपयुक्त जब तक आप वास्तव में (न केवल तारीखें) एक सार्थक संस्करण नीति है, मैं @since टैग से छुटकारा पाने होता है ...)
• ।
• स्रोत बताते हुए का कोई मतलब नहीं है फ़ाइल
• "इंटरफ़ेस क्लास जिसमें निम्न विधियां हैं" का विवरण अर्थहीन और विरोधाभासी है (एक इंटरफेस एक वर्ग नहीं है)। जो भी जावाडोक पढ़ रहा है वह पहले से ही विधियों की सूची देख पाएगा। आपको यहां अतिरिक्त जानकारी प्रदान करने की कोशिश करनी चाहिए।

बस सामान्य वर्ग प्रलेखन के लिए की तरह

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