सी #

Question

में इंटरफ़ेस और कार्यान्वयन टिप्पणियों को सिंक्रनाइज़ करने के तरीके इंटरफ़ेस और उसके कार्यान्वयन के बीच टिप्पणियों को सिंक करने के स्वचालित तरीके हैं? मैं वर्तमान में उन्हें दोनों दस्तावेज कर रहा हूं और उन्हें मैन्युअल रूप से सिंक में रखना नहीं चाहूंगा।

अद्यतन: जब मैं इस तरह वर्ग बनाने

interface IFoo{ 
    /// <summary> 
    /// Commenting DoThis method 
    /// </summary> 
    void DoThis(); 
} 
class Foo : IFoo { 
    public void DoThis(); 
} 

:

IFoo foo=new Foo(); 
foo.DoThis();//comments are shown in intellisense 

यहाँ टिप्पणी नहीं दिखाए जाते हैं:

इस कोड पर विचार करें

Foo foo=new Foo(); 
foo.DoThis();//comments are not shown in intellisense 

<inheritDoc/> टैग पूरी तरह से रेत कैसल में प्रलेखन उत्पन्न करेगा, लेकिन यह इंटेलिजेंस टूलटिप्स में काम नहीं करता है।

कृपया अपने विचार साझा करें।

धन्यवाद।

Answer 1

आप माइक्रोसॉफ़्ट सैंडकासल (या एनडीओसी) inheritdoc टैग का उपयोग करके इसे आसानी से कर सकते हैं। यह आधिकारिक तौर पर विनिर्देशन द्वारा समर्थित नहीं है, लेकिन कस्टम टैग पूरी तरह से स्वीकार्य हैं, और वास्तव में माइक्रोसॉफ्ट ने सैंडकैसल बनाया जब एनडीओसी से इस (और एक या दो अन्य टैग) की प्रतिलिपि बनाना चुना।

/// <inheritdoc/> 
/// <remarks> 
/// You can still specify all the normal XML tags here, and they will 
/// overwrite inherited ones accordingly. 
/// </remarks> 
public void MethodImplementingInterfaceMethod(string foo, int bar) 
{ 
    // 
} 

Here सैंडकैसल मदद फ़ाइल बिल्डर जीयूआई है, जो पूरी तरह से अपने उपयोग का वर्णन से मदद पेज है।

(बेशक, यह नहीं विशेष रूप से "तुल्यकालन", के रूप में अपने प्रश्न का उल्लेख है, लेकिन यह वास्तव में क्या आप के लिए देख रहे हैं फिर भी होने लगते हैं।)

एक नोट के रूप में, यह एक तरह लगता है मेरे लिए पूरी तरह से उचित विचार, हालांकि मैंने देखा है कि कुछ लोग सोचते हैं कि आपको हमेशा व्युत्पन्न और कार्यान्वित कक्षाओं में टिप्पणियों को दोबारा निर्दिष्ट करना चाहिए। (मैंने वास्तव में इसे अपने पुस्तकालयों में से एक को दस्तावेज करने में स्वयं किया है और मुझे कोई भी समस्या नहीं दिखाई दे रही है।) टिप्पणियों के लिए लगभग हमेशा कोई कारण नहीं है, तो क्यों न केवल उत्तराधिकारी और इसे आसान तरीके से करें?

संपादित करें: आपके अपडेट के बारे में, Sandcastle भी आपके लिए इसका ख्याल रख सकता है। Sandcastle इनपुट के लिए उपयोग की जाने वाली वास्तविक XML फ़ाइल के एक संशोधित संस्करण को आउटपुट कर सकता है, जिसका अर्थ है कि आप इस संशोधित संस्करण को अपने लाइब्रेरी DLL के साथ सीधे विजुअल स्टूडियो द्वारा निर्मित एक के बजाय वितरित कर सकते हैं, जिसका अर्थ है कि आपके पास इंटेलिजेंस में टिप्पणियां हैं साथ ही प्रलेखन फ़ाइल (सीएचएम, जो कुछ भी)।

Answer 2

ऐसा मत करो। इस तरह से सोचें - यदि दोनों टिप्पणियां हर समय एक जैसी होती हैं, तो उनमें से एक आवश्यक नहीं है। टिप्पणी के लिए एक कारण होना चाहिए (प्रत्येक फंक्शन और वैरिएबल को टिप्पणी करने के लिए किसी तरह की अजीब दायित्व के अलावा) ताकि आपको यह पता लगाना पड़े कि वह अनूठा कारण क्या है और दस्तावेज है।

Answer 3

मैं आमतौर पर इस तरह की टिप्पणियां लिखें:

/// <summary> 
/// Implements <see cref="IMyInterface.Foo(string, int)"/> 
/// </summary> 
/// <returns></returns> 

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

संपादित करें:

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

Answer 4

GhostDoc आज़माएं! यह मेरे लिए काम करता है :-)

संपादित करें: अब जब कि मैं <inheritdoc/> के लिए सैंडकैसल के समर्थन से अवगत कराया गया है, मैं Noldorin पद समर्थन करते हैं। यह एक बेहतर समाधान है। हालांकि, मैं अभी भी सामान्य आधार पर GhostDoc की अनुशंसा करता हूं।

Answer 5

यदि आप पहले से इसका उपयोग नहीं कर रहे हैं, तो मैं GhostDoc नामक एक निःशुल्क विजुअल स्टूडियो एडन की दृढ़ता से अनुशंसा करता हूं। यह प्रलेखन प्रक्रिया को आसान बनाता है। कुछ हद तक संबंधित प्रश्न पर my comment पर एक नज़र डालें।

हालांकि GhostDoc स्वचालित रूप से तुल्यकालन नहीं होगा, यह इस परिदृश्य में आपकी मदद कर सकते हैं:

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

जाओ विकल्प -> कीबोर्ड सेटिंग्स, और GhostDoc.AddIn.RebuildDocumentation के लिए एक महत्वपूर्ण (मैं Ctrl-Shift-Alt-D प्रयुक्त) आवंटित। alt text http://i44.tinypic.com/10dd1f9.png

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

Answer 6

/// <inheritDoc/> 

Read here

Use this

Answer 7

ReSharper साथ

आप इसे कॉपी कर सकते हैं, लेकिन मुझे नहीं लगता है कि यह सब समय सिंक में है।

Answer 8

मेरे पास एक बेहतर उत्तर है: FiXml।

निश्चित रूप से काम कर रहा है दृष्टिकोण क्लोनिंग, लेकिन यह महत्वपूर्ण नुकसान, उदा है .:

• जब मूल टिप्पणी बदल जाता है (जो अक्सर विकास के दौरान होता है), अपने क्लोन नहीं है।
• आप बड़ी मात्रा में डुप्लीकेट बना रहे हैं। यदि आप स्रोत कोड विश्लेषण टूल (जैसे टीम सिटी में डुप्लिकेट फाइंडर) का उपयोग कर रहे हैं, तो यह मुख्य रूप से आपकी टिप्पणियां पायेगा।

के रूप में यह उल्लेख किया गया था, वहाँ Sandcastle में <inheritdoc> टैग है, लेकिन यह FiXml की तुलना में कुछ नुकसान हैं:

• सैंडकैसल संकलित HTML मदद फ़ाइलों का उत्पादन - सामान्य रूप से यह .xml संशोधित नहीं करता है निकाली गई एक्सएमएल टिप्पणियों वाली फाइलें (आखिरकार, यह संकलन के दौरान "फ्लाई पर" नहीं किया जा सकता है)।
• Sandcastle का कार्यान्वयन कम शक्तिशाली है। जैसे <see ... copy="true" /> है।

अधिक जानकारी के लिए Sandcastle's <inheritdoc> description देखें।

FiXml का संक्षिप्त वर्णन: यह सी # \ विजुअल बेसिक .NET द्वारा उत्पादित XML दस्तावेज़ का एक पोस्ट प्रोसेसर है। इसे एमएसबिल्ड कार्य के रूप में लागू किया गया है, इसलिए इसे किसी भी परियोजना में एकीकृत करना काफी आसान है।

• आधार वर्ग या इंटरफ़ेस से प्रलेखन इनहेरिट के लिए कोई समर्थन: यह कुछ कष्टप्रद इन भाषाओं में एक्सएमएल प्रलेखन लेखन से संबंधित मामलों संबोधित करते हैं। आईई। किसी भी ओवरराइड सदस्य के लिए एक प्रलेखन स्क्रैच से लिखा जाना चाहिए, हालांकि आमतौर पर यह कम से कम उस हिस्से के उत्तराधिकारी के लिए काफी वांछनीय है।
• जैसे आमतौर पर इस्तेमाल किया प्रलेखन टेम्पलेट्स, की प्रविष्टि के लिए कोई समर्थन "इस प्रकार का सिंगलटन है -। अपने <see cref="Instance" /> संपत्ति का उपयोग इसके बारे में केवल उदाहरण के लिए", या "<CurrentType> वर्ग का एक नया उदाहरण आरंभीकृत।"

उल्लेख मुद्दों को हल करने के लिए निम्न अतिरिक्त एक्सएमएल टैग प्रदान की जाती हैं:

• <inheritdoc />, <inherited /> टैग
• <see cref="..." copy="..." /> attrib <see/> टैग में ute।

यहां its web page और download page है।

Answer 9

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

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

www.inheritdoc.io पर अधिक जानकारी (मुफ्त संस्करण उपलब्ध)।