टिप्पणी सी # के लिए विरासत (वास्तव में किसी भी भाषा)

Question

मान लीजिए कि मेरे पास यह इंटरफ़ेस है

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

और यह वर्ग

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

क्या कोई रास्ता है, या कोई ऐसा उपकरण है जो मुझे प्रत्येक सदस्य की टिप्पणियों में बेस क्लास या इंटरफ़ेस में डाल सकता है?

क्योंकि मुझे प्रत्येक व्युत्पन्न उप-वर्ग के लिए समान टिप्पणियों को फिर से लिखने से नफरत है!

Comments

मैं न केवल इससे नफरत करता हूं बल्कि उन्हें सिंक में रखना भी मुश्किल है।

— ओलिवियर जैकोट-डेसकोम्बेस

Answer 1

घोस्टडॉक ठीक यही करता है। उन तरीकों के लिए जिन्हें विरासत में नहीं मिला है, यह नाम से बाहर एक विवरण बनाने की कोशिश करता है।

FlingThing() हो जाता है "Flings the Thing"

Comments

घोस्टडॉक कमाल का है, उन चीजों में से एक जो मुझे नहीं पता था कि मुझे इसकी आवश्यकता है लेकिन अब मैं इसके बिना नहीं कर सकता: ओ)

— निकोलाईडेंट डे

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

— लैंसफ्लारे 12

@Lensflare यह सच है। मुझे एक बार एक फ्रेमवर्क का उपयोग करना पड़ा था जिसमें केवल इस तरह की उत्पन्न टिप्पणियां थीं, जिसने विधि / वर्ग में कोई जानकारी नहीं जोड़ी। इसके बजाय "यह विधि ऐसा करती है और यह कि" टिप्पणियां जहां "जैसे यह कक्षा Z की विधि XY है"। xD इसके अलावा आप कोड को ब्राउज़ नहीं करते हैं, इसलिए यह परीक्षण और त्रुटि के लिए नीचे चला गया। फिर कभी नहीं! :-)

— itmuckel

@Lensflare, जबकि मैं 100% सहमत हूँ कि जहाँ तक AGDs पर निर्भर है , मुझे इस बात पर ध्यान देना चाहिए कि AGDs का उपयोग "सभी ऐसे करें" जैसे जादुई बटन के लिए नहीं किया जाता है। इसके बजाय, उन्हें बॉयलरप्लेट की मात्रा को कम करने के लिए टेम्पलेट-जनरेटर के रूप में उपयोग किया जाता है, दोहराए जाने वाले प्रलेखन को आपको स्वयं लिखना होगा, ताकि आप महत्वपूर्ण सामान पर ध्यान केंद्रित कर सकें। --- उदाहरण के लिए, यह उत्पन्न कर सकते हैं <summary>, <param>, <returns>, <throws>, etc...आप के लिए वर्गों। कई बार अच्छे-अच्छे परिणामों के साथ; अन्य समय में सुधार या विस्तार की जरूरत है, लेकिन फिर भी समग्र प्रयास को कम कर रहा है।

— XenoRo

लोगों के लिए प्रलेखन यह आर्किटेक्ट के लिए नहीं है, इसलिए उनके चूतड़ सभी कवर किए गए हैं: "अरे, क्या हम आपकी परियोजना के कोड प्रलेखन को पढ़ सकते हैं? निश्चित रूप से, यहां यह है।"

— त्रिशूल

Answer 2

आप हमेशा <inheritdoc />टैग का उपयोग कर सकते हैं ।

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

Comments

मुझे पता नहीं था <inheritdoc /> यहां तक ​​कि मौजूद है ... लेकिन जहां तक ​​मैं देख सकता हूं, इस पद्धति के लिए टिप्पणी अंतर्मुखी के साथ दिखाई नहीं देती है।

— गेरेलिम

@gerleim एक साल पहले से जेफ हेटन के जवाब और इसके नीचे की टिप्पणी को देखें। सैंडकैसल में <inheritdoc /> है, C # नहीं।

— rbwhitaker

मैं इनहेरिटोकॉक के साथ इंटेलीसेंस में इंटरफ़ेस से टिप्पणियां देखता हूं, और यह भी कि अगर व्युत्पन्न वर्ग पर कोई कोड-डॉक नहीं है। लेकिन ऐसा इसलिए हो सकता है क्योंकि मेरे पास पुनर्जीवन है।

— टिम एबेल

Resharper 2017.2 ने inheritdoc jetbrains.com/resharper/whatsnew के

— Dav Evans

विजुअल स्टूडियो एंटरप्राइज 2017 (संस्करण 15.9.3) मेरे लिए विरासत में मिली टिप्पणियों को नहीं दिखाता है।

— हर्ज़ेबूब

Answer 3

/// <inheritdoc/>अगर आपको विरासत चाहिए तो इस्तेमाल करें । घोस्टडॉक या ऐसा कुछ भी करने से बचें।

मैं मानता हूं कि यह कष्टप्रद है कि टिप्पणियां विरासत में नहीं मिली हैं। यह एक बहुत ही सरल ऐड-इन होगा, अगर किसी के पास समय हो (मुझे लगता है कि मैंने किया था)।

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

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

Comments

मैं उलझन में हूँ - आपने कहा कि घोस्टडॉक से बचें, लेकिन अंत में आपको प्रतीत होता है कि घोस्टडॉक ने चीजों को आसान बनाने में मदद की है। क्या आप स्पष्ट कर सकते हैं कि आपका क्या मतलब है?

— माइक मेरीनोव्स्की

साभार @MikeMarynowski यह पुरानी सलाह है। मुझे लगता है कि मैं उस समय कहना चाहता था कि घोस्टडॉक, किसी भी अन्य जनरेटर की तरह, टिप्पणियों को जोड़ देगा लेकिन लगभग बेकार विस्तार जैसे <param name="origin">The origin.</param>। देखें घोस्टडॉक अधिक उदाहरणों के लिए सबसे अच्छी बातें कहता है । विजुअल स्टूडियो में अब xmldocs के लिए बहुत बेहतर लाइनिंग और जेनरेटर हैं, जो आपको यह बताने के लिए कि पैरामीटर + डॉक्स को अलाइन नहीं करते हैं इसलिए घोस्टडॉक (या अन्य टूल) की आवश्यकता नहीं है।

— डेनिस

Answer 4

जावा के पास यह है, और मैं हर समय इसका उपयोग करता हूं। बस करो:

/**
 * {@inheritDoc}
 */

और जावदोक टूल ने इसका पता लगाया।

C # में समान मार्कर है:

<inheritDoc/>

आप यहां और अधिक पढ़ सकते हैं:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

Comments

C # में <inheritdoc/>मार्कर नहीं है : सैंडकास्टेल के पास है। shfb.codeplex.com

— एरिक

एक उपयोगकर्ता वॉयस सुविधा अनुरोध है जो <inheritdoc /> को C # में जोड़ने का अनुरोध करता है। ऊपर जाकर इसे visualstudio.uservoice.com/forums/121579-visual-studio/…

— deadlydog

न तो सी # और न ही जावा (न ही कोई अन्य प्रोग्रामिंग भाषा) में "एक्सएमएल डॉक्टर" तत्वों में से कोई भी है। ये टिप्पणियां हैं । संकलक उनके बारे में कुछ भी नहीं जानते हैं। वे सभी तृतीय-पक्ष प्रलेखन जनरेटर द्वारा उपयोग किए जाने वाले सख्त हैं, चाहे वह जादवॉक या सैंडकास्टल हो या जो भी हो।

— जेम्स क्यूरन

जब Java या C # कहा जाता है, तो यह USUALLY का अर्थ है संबद्ध उपकरणों का समुदाय। बहुत ही शाब्दिक अर्थों में न तो जावा और न ही सी # की क्षमता है। यह एक शैक्षणिक तर्क होगा कि जावा या सी # में डेटाबेस से जुड़ने की क्षमता का अभाव है, क्योंकि रन टाइम लाइब्रेरी ऐसा करती है।

— जेफ हेटन

दृश्य स्टूडियो संस्करण 16.4.0 और नया <inheritDoc /> के लिए इंटेलीजेंस प्रदान करता है! docs.microsoft.com/en-us/visualstudio/releases/2019/…

— ashbygeek

Answer 5

मैं सीधे उपयोग करने के लिए कहूंगा

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

तथा

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

आपको यह टिप्पणी सिर्फ अपनी कक्षा / विधि की पिछली पंक्ति में रखनी होगी

यह आपके टिप्पणियों की जानकारी उदाहरण के लिए एक इंटरफ़ेस से प्राप्त करेगा जिसे आपने इस तरह से प्रलेखित किया है:

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Comments

सलाह के लिए धन्यवाद! यह दृष्टिकोण अधिक स्पष्ट है और ऑब्जेक्ट क्लास (यहां तक ​​कि इंटरफ़ेस को लागू करते समय) से वंशानुक्रम वर्ग विवरण की समस्या को हल करता है।

— डेनिस बेबरीकिन

Answer 6

Resharper में बेस क्लास या इंटरफ़ेस से टिप्पणियों को कॉपी करने का विकल्प होता है।

Comments

ओह? कैसे? मैं ReSharper का उपयोग करता हूं और मैंने इंटरफ़ेस को लागू करते या इनहेरिट करते समय उस विकल्प को कभी नहीं देखा है ... यह कहां है और आप उस विकल्प का उपयोग कैसे करते हैं?

— जाजिमोव

@Jazimov जब आप Alt + को ओवरराइड विधि दर्ज करते हैं, तो "आधार से दस्तावेज़ कॉपी करें" का विकल्प होता है।

— svick

Answer 7

एक अन्य तरीका <see />XML प्रलेखन टैग का उपयोग करना है । यह कुछ अतिरिक्त प्रयास है लेकिन बॉक्स से बाहर काम करता है ...

यहाँ कुछ उदाहरण हैं:

/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

अपडेट करें:

मैं अब उपयोग करना पसंद करता हूं /// <inheritdoc/>जो अब ReSharper द्वारा समर्थित है।

Answer 8

मैंने XML दस्तावेज़ीकरण फ़ाइलों में <inheritdoc/>टैग को बदलने के लिए समर्थन जोड़ने के लिए XML दस्तावेज़ फ़ाइलों को पोस्ट-प्रोसेस करने के लिए एक उपकरण बनाना समाप्त कर दिया। Www.inheritdoc.io पर उपलब्ध (मुफ्त संस्करण उपलब्ध)।

Answer 9

खैर, एक प्रकार का मूल समाधान है, मैंने .NET कोर 2.2 के लिए पाया

विचार का उपयोग करना है <include>टैग ।

आप <GenerateDocumentationFile>true</GenerateDocumentationFile>अपने जोड़ सकते हैं.csproj फ़ाइल ।

आपके पास एक इंटरफ़ेस हो सकता है:

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

और कुछ ऐसा है जो इसे विरासत में मिला है:

using System;

namespace YourNamespace
{
    /// <summary>
    /// A type inherited from <see cref="IType"/> interface.
    /// </summary>
    public class InheritedType : IType
    {
        /// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
        public void ExecuteAction() => Console.WriteLine("Action is executed.");
    }
}

ठीक है, यह थोड़ा डरावना है, लेकिन यह अपेक्षित तत्वों को जोड़ता है YourNamespace.xml।

यदि आप Debugकॉन्फ़िगरेशन बनाते हैं , तो आप टैग की विशेषता के Releaseलिए स्वैप कर सकते हैं ।Debugfileinclude

एक सही पता लगाने के लिए member's nameबस खुला उत्पन्न संदर्भित करने के लिए Documentation.xmlफ़ाइल।

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

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

मेरी परियोजना में, मैं दोनों के लिए <inheritdoc/>(DocFX के लिए) और <include/>(NuGet पैकेज प्रकाशित करने के लिए ) और स्टूडियो स्टूडियो में सत्यापन के लिए समाप्त हो गया है :

        /// <inheritdoc />
        /// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
        public void ExecuteReadOperation(Action action) => action();