C # [बंद] में इंटरफ़ेस और कार्यान्वयन टिप्पणियों को सिंक्रनाइज़ करने के तरीके

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/>टैग पूरी तरह से रेत के महल में प्रलेखन उत्पन्न होगा, लेकिन यह IntelliSense टूलटिप्स में काम नहीं करता।

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

धन्यवाद।

Comments

This क्या यह सुविधा लागू की गई है? visualstudio.uservoice.com/forums/121579-visual-studio/…

— नर्कबॉय

यदि मैं इंटरफ़ेस के लिए प्रलेखन उपलब्ध है तो मैं एटोमिनेर प्रो कैसे बना सकता हूं?

— नर्कबॉय

आप सही हैं <inheritdoc/>Visual Studio में टूट गया है। कृपया बग रिपोर्ट के लिए visualstudio.uservoice.com/forums/121579-visual-studio/…

— कर्नल पैनिक

Answer 1

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

/// <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)
{
    //
}

यहां सैंडकैसल हेल्प फाइल बिल्डर जीयूआई से सहायता पृष्ठ है, जो इसके उपयोग का पूर्ण वर्णन करता है।

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

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

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

Comments

अरे, यह बहुत अच्छा है! मुझे सैंडकास्टल पसंद है!

— तोर हौगेन

अद्यतन प्रश्न का उत्तर देने के लिए पोस्ट संपादित की गई।

— नोल्डोरिन

क्या इसे कक्षा स्तर पर किया जा सकता है? ताकि मुझे हर विधि से पहले /// <inheritdoc /> नहीं डालना पड़े।

— एंटनी स्कॉट

एक चीज़ जो मैंने देखी है, वह <inheritdoc/> यह है कि <param>टैग के लिए दस्तावेज़ विरासत में नहीं मिला है ।

— स्टीफन

ऊपर से वोट के लिए जाओ इस प्रयोक्ता आवाज सुविधा के लिए <inheritdoc /> आधिकारिक तौर पर वी.एस. के साथ सी # कल्पना और काम करने के लिए जोड़ा IntelliSense visualstudio.uservoice.com/forums/121579-visual-studio/...

— deadlydog

Answer 2

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

हालांकि घोस्टडॉक स्वचालित रूप से सिंक्रोनाइज़ेशन नहीं करेगा, यह निम्नलिखित परिदृश्य में आपकी मदद कर सकता है:

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

विकल्प पर जाएँ -> कीबोर्ड सेटिंग्स, और एक कुंजी असाइन करें GhostDoc.AddIn.RebuildDocumentation(मैंने इस्तेमाल किया Ctrl-Shift-Alt-D)।

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

Comments

घोस्टडॉक का नवीनतम संस्करण (5.3.16270) भी विरासत में मिला है। मैंने इसे केवल अपने इंटरफ़ेस कार्यान्वयन के लिए आज़माया। अच्छा बोनस, यह फेंके गए अपवाद के संदेश के साथ अपवादों को भी जोड़ता है :-)

— क्रिस्टोफ़

Answer 3

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

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

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

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

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

Answer 4

घोस्टडॉक की कोशिश करो ! इससे मेरा काम बनता है :-)

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

Comments

व्यक्तिगत रूप से मुझे घोस्टडॉक पसंद नहीं है। यह प्रलेखन उत्पन्न करता है जहां वास्तव में कोई नहीं है। यह इस तथ्य को छिपा रहा है कि कुछ दस्तावेज नहीं है। बस एक निजी राय, मैं यह नहीं कहता कि यह सामान्य रूप से कुछ बुरा है।

— स्टेफन स्टाइनगर

स्टीफन की टिप्पणी से सहमत हूँ कि घोस्टडॉक सही नहीं है, हालांकि यह स्वचालित रूप से "विरासत में मिली" टिप्पणियों को इस तरह खींचती है ताकि यह सवाल का एक अच्छा जवाब हो।

— स्टीव

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

— Tor Haugen

Answer 5

मेरे पास एक बेहतर उत्तर है: FiXml ।, मैं इसके लेखकों में से एक हूं

क्लोनिंग निश्चित रूप से काम कर रहा है, लेकिन इसके महत्वपूर्ण नुकसान हैं, जैसे:

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

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

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

सैंडकैसल का विवरण देखें<inheritdoc> अधिक जानकारी के लिए।

FiXml का संक्षिप्त विवरण: यह C # \ Visual Basic .Net द्वारा निर्मित XML दस्तावेज़ का पोस्ट-प्रोसेसर है। इसे MSBuild कार्य के रूप में लागू किया गया है, इसलिए इसे किसी भी परियोजना में एकीकृत करना काफी आसान है। यह इन भाषाओं में XML प्रलेखन लिखने से संबंधित कुछ कष्टप्रद मामलों को संबोधित करता है:

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

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

• <inheritdoc />, <inherited /> टैग
• <see cref="..." copy="..." /><see/>टैग में विशेषता ।

यहाँ इसका वेब पेज और डाउनलोड पेज है ।

Answer 6

/// <inheritDoc/>

यहाँ पढ़ें

इसे इस्तेमाल करो

Answer 7

मैंने <inheritdoc /> टैग के लिए समर्थन जोड़ने के लिए XML प्रलेखन फ़ाइलों को पोस्ट-प्रोसेस करने के लिए एक पुस्तकालय बनाया।

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

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

Answer 8

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

Comments

मैं यहाँ इंटरफ़ेस का उपयोग नहीं करता था मैं इसे परीक्षणों में फीका नहीं कर रहा था।

— वैलेंटाइन वसीलीव

Answer 9

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