Ereditarietà dei commenti per C # (in realtà qualsiasi linguaggio)

Supponiamo che io abbia questa interfaccia

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

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

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

E questa classe

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

Esiste un modo o esiste uno strumento che mi consenta di inserire automaticamente i commenti di ogni membro in una classe o interfaccia base?

Perché odio riscrivere gli stessi commenti per ogni sottoclasse derivata!

GhostDoc fa esattamente questo. Per i metodi che non sono ereditati, cerca di creare una descrizione dal nome.

FlingThing() diventa "Flings the Thing"

Puoi sempre usare <inheritdoc />tag.

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

Uso /// <inheritdoc/> se vuoi l'eredità. Evita GhostDoc o qualcosa del genere.

Sono d'accordo che sia fastidioso che i commenti non vengano ereditati. Sarebbe un componente aggiuntivo abbastanza semplice da creare se qualcuno avesse il tempo (vorrei averlo fatto).

Detto questo, nella nostra base di codice inseriamo commenti XML solo sulle interfacce e aggiungiamo commenti di implementazione extra alla classe. Questo funziona per noi poiché le nostre classi sono private / interne e solo l'interfaccia è pubblica. Ogni volta che utilizziamo gli oggetti tramite le interfacce, i commenti completi vengono visualizzati nell'intelligenza.

GhostDoc è un buon inizio e ha reso il processo più semplice per scrivere commenti. È particolarmente utile mantenere i commenti aggiornati quando aggiungi / rimuovi parametri, riesegui GhostDoc e aggiornerà la descrizione.

Java ha questo e lo uso sempre. Basta fare:

/**
 * {@inheritDoc}
 */

E lo strumento Javadoc lo capisce.

C # ha un marcatore simile:

<inheritDoc/>

Puoi leggere di più qui:

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

Direi di utilizzare direttamente il file

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

E

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

Devi mettere questi commenti solo sulla riga precedente della tua classe / metodo

Questo otterrà le informazioni dei tuoi commenti, ad esempio, da un'interfaccia che hai documentato come:

    /// <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);

Resharper ha un'opzione per copiare i commenti dalla classe di base o dall'interfaccia.

Un altro modo è usare il <see /> tag di documentazione XML. Questo è uno sforzo in più ma funziona fuori dagli schemi ...

Ecco alcuni esempi:

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

Aggiornare:

Ora preferisco usare /// <inheritdoc/>che ora è supportato da ReSharper.

Ho finito per creare uno strumento per post-elaborare i file di documentazione XML per aggiungere il supporto per la sostituzione del <inheritdoc/>tag nei file di documentazione XML stessi. Disponibile su www.inheritdoc.io (versione gratuita disponibile).

Bene, c'è una sorta di soluzione nativa che ho trovato per .NET Core 2.2

L'idea è usare <include> tag.

Puoi aggiungere il <GenerateDocumentationFile>true</GenerateDocumentationFile>tuo.csproj file di a.

Potresti avere un'interfaccia:

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

E qualcosa che eredita da esso:

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.");
    }
}

Ok, fa un po 'paura, ma aggiunge gli elementi attesi al file YourNamespace.xml.

Se si costruisce Debugla configurazione, è possibile scambiare Releaseper l'attributo del tag.Debugfileinclude

Per trovare un corretto member's namedi riferimento generato basta aprire Documentation.xmlil file.

Presumo inoltre che questo approccio richieda la creazione di un progetto o di una soluzione almeno due volte (la prima volta per creare un file XML iniziale e la seconda per copiare elementi da esso a se stesso).

Il lato positivo è che Visual Studio convalida gli elementi copiati, quindi è molto più facile mantenere la documentazione e il codice sincronizzati con l'interfaccia / classe base, ecc. (Ad esempio nomi di argomenti, nomi di parametri di tipo, ecc.).

Nel mio progetto, sono finito con entrambi <inheritdoc/>(per DocFX) e <include/>(per la pubblicazione di pacchetti NuGet e per la convalida in Visual Studio):

        /// <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();