इंटरफ़ेस, कार्यान्वयन या दोनों पर टिप्पणी करें?

Question

मुझे कल्पना है कि हम सभी (जब हमें परेशान किया जा सकता है!) हमारे इंटरफेस पर टिप्पणी करें। जैसे

/// <summary> 
/// Foo Interface 
/// </summary> 
public interface Foo 
{ 
    /// <summary> 
    /// Will 'bar' 
    /// </summary> 
    /// <param name="wibble">Wibble factor</param> 
    void Bar(string wibble); 
} 

आप भी कार्यान्वयन (जो भी जैसे एक एक पुस्तकालय के भाग के रूप में ग्राहकों के लिए उपलब्ध कराया जा सकता,) टिप्पणी है? यदि ऐसा है तो आप दोनों को सिंक में कैसे प्रबंधित करते हैं? या आप बस 'दस्तावेज़ीकरण के लिए इंटरफेस देखें' टिप्पणी जोड़ें?

धन्यवाद

Answer 1

एक सामान्य नियम के रूप देव के लिए कर रहे हैं, मैं एक ही सूखी का उपयोग कोड के साथ के रूप में (खुद को दोहराना नहीं) सिद्धांत:

• पर इंटरफेस, इंटरफ़ेस
कार्यान्वयन पर
• दस्तावेज़, दस्तावेज़ कार्यान्वयन बारीकियों

जावा विशिष्ट: जब कार्यान्वयन का दस्तावेजीकरण, उस {@inheritDoc} के लिए टैग "में शामिल हैं" javadocs च इंटरफ़ेस रोम।

अधिक जानकारी के लिए:

• Official javadoc documentation
• कुछ अनौपचारिक advice।

Answer 2

आप GhostDoc ऐड उपयोग करते हैं, यह इंटरफ़ेस से टिप्पणी के साथ कार्यान्वयन अपडेट हो जाता है जब आप सही क्लिक करें और पद्धति पर "दस्तावेज़ इस" का चयन करें।

Answer 3

इंटरफ़ेस पर टिप्पणी करना वास्तविक कार्यान्वयन का उपयोग करने के तरीके को समझने के लिए पर्याप्त दस्तावेज़ीकरण होना चाहिए। कार्यान्वयन में टिप्पणियां जोड़ने का एकमात्र समय यह है कि यदि इसमें निजी कार्य हैं जो इंटरफ़ेस को संतुष्ट करने के लिए डाले गए थे, हालांकि वे केवल आंतरिक टिप्पणियां होंगी और ऑनलाइन दस्तावेज़ों में या ग्राहकों के लिए उपलब्ध नहीं दिखाई देंगे।

कार्यान्वयन केवल यही है, जब तक वे इंटरफ़ेस के अनुरूप होते हैं, उन्हें अलग-अलग दस्तावेज़ों की आवश्यकता नहीं होती है।

Answer 4

केवल इंटरफ़ेस। दोनों पर टिप्पणी दोहराव है और यह संभव है कि कोड बदलते समय टिप्पणी के दो सेट अंततः सिंक हो जाएंगे। "MyInterface लागू करता है" के साथ कार्यान्वयन पर टिप्पणी करें ... Doxygen जैसी चीजें डॉक्स उत्पन्न करती हैं जिसमें व्युत्पन्न दस्तावेज़ों को कार्यान्वयन के लिए दस्तावेज़ों में शामिल किया जाता है (यदि आप उन्हें सही तरीके से सेट करते हैं)।

Answer 5

सी # के लिए यह आईएमओ पर निर्भर करता है: यदि आप स्पष्ट इंटरफ़ेस कार्यान्वयन का उपयोग करते हैं, तो मैं कार्यान्वयन दस्तावेज नहीं करता।

हालांकि आप इंटरफ़ेस सीधे लागू करने और अपनी वस्तु तो इन तरीकों भी प्रलेखित किया जाना चाहिए के साथ इंटरफेस के सदस्यों का पर्दाफाश करता है, तो।

नाथ ने कहा, आप GhostDoc का उपयोग कार्यान्वयन में एक इंटरफ़ेस के दस्तावेज़ को स्वचालित रूप से सम्मिलित करने के लिए कर सकते हैं। मैंने दस्तावेज़ को इस आदेश को Ctrl + Shift + D शॉर्टकट में मैप किया है और यह उस कुंजीस्ट्रोक में से एक है जिसे मैं लगभग स्वचालित रूप से दबाता हूं। मेरा मानना ​​है कि रीशेर्पर के पास इंटरफ़ेस के दस्तावेज़ को सम्मिलित करने का विकल्प भी है, जब यह आपके लिए विधियों को लागू करता है।

Answer 6

हम सिर्फ इंटरफेस टिप्पणी, टिप्पणी से तालमेल न बिठा पाने के लिए इतना आसान कर रहे हैं या तो व्युत्पन्न या आधार वर्ग/इंटरफेस कि यह सिर्फ एक ही स्थान पर यह करना अच्छा है।

हालांकि ऐसा लगता है कि @Nath शायद एक स्वचालित प्रलेखन उपकरण है जो चीजों को एक साथ रखने में मदद करता सुझाव दे (शांत लग रहा है, तो आपको लगता है कि का उपयोग करें)। यहाँ पर WhereIWorkAndYouDontCare टिप्पणियां इसलिए कोड में एक ही स्थान पसंद किया जाता है

Answer 7

मैं एक उपकरण है जो < inheritdoc/> टैग के लिए समर्थन जोड़ने के लिए बाद संसाधित करता है एक्सएमएल दस्तावेज़ फ़ाइलों बनाया।

हालांकि यह स्रोत कोड में इंटेलिसेंस के साथ मदद नहीं करता है, यह संशोधित XML दस्तावेज़ फ़ाइलों को NuGet पैकेज में शामिल करने की अनुमति देता है और इसलिए संदर्भित NuGet संकुल में इंटेलिजेंस के साथ काम करता है।

यह www.inheritdoc.io (मुफ़्त संस्करण उपलब्ध है) पर है।