Kommentar Vererbung für C # (eigentlich jede Sprache)

Angenommen, ich habe diese Schnittstelle

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

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

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

Und diese Klasse

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

Gibt es eine Möglichkeit oder gibt es ein Tool, mit dem ich die Kommentare jedes Mitglieds in einer Basisklasse oder Schnittstelle automatisch einfügen kann?

Weil ich es hasse, die gleichen Kommentare für jede abgeleitete Unterklasse neu zu schreiben!

GhostDoc macht genau das. Bei Methoden, die nicht vererbt werden, wird versucht, aus dem Namen eine Beschreibung zu erstellen.

FlingThing() wird "Flings the Thing"

Sie können immer <inheritdoc />Tag verwenden.

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

Verwenden /// <inheritdoc/>Sie diese Option, wenn Sie eine Vererbung wünschen. Vermeiden Sie GhostDoc oder ähnliches.

Ich bin damit einverstanden, dass es ärgerlich ist, dass Kommentare nicht vererbt werden. Es wäre ein ziemlich einfaches Add-In zu erstellen, wenn jemand die Zeit hätte (ich wünschte, ich hätte es getan).

In unserer Codebasis fügen wir jedoch nur XML-Kommentare zu den Schnittstellen hinzu und fügen der Klasse zusätzliche Implementierungskommentare hinzu. Dies funktioniert für uns, da unsere Klassen privat / intern sind und nur die Schnittstelle öffentlich ist. Jedes Mal, wenn wir die Objekte über die Schnittstellen verwenden, werden vollständige Kommentare in Intelligenz angezeigt.

GhostDoc ist ein guter Anfang und hat das Schreiben von Kommentaren erleichtert. Es ist besonders nützlich, die Kommentare auf dem neuesten Stand zu halten, wenn Sie Parameter hinzufügen / entfernen, GhostDoc erneut ausführen und die Beschreibung aktualisieren.

Java hat das und ich benutze es die ganze Zeit. Mach einfach:

/**
 * {@inheritDoc}
 */

Und das Javadoc-Tool findet es heraus.

C # hat einen ähnlichen Marker:

<inheritDoc/>

Hier können Sie mehr lesen:

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

Ich würde sagen, die direkt zu verwenden

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

Und

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

Sie müssen diese Kommentare nur in die vorherige Zeile Ihrer Klasse / Methode einfügen

Dadurch erhalten Sie die Informationen Ihrer Kommentare beispielsweise von einer Schnittstelle, die Sie wie folgt dokumentiert haben:

    /// <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 bietet die Möglichkeit, die Kommentare aus der Basisklasse oder der Schnittstelle zu kopieren.

Eine andere Möglichkeit ist die Verwendung des <see />XML-Dokumentations-Tags. Dies ist ein zusätzlicher Aufwand, funktioniert aber sofort ...

Hier sind einige Beispiele:

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

Aktualisieren:

Ich bevorzuge jetzt die Verwendung, /// <inheritdoc/>die jetzt von ReSharper unterstützt wird.

Am Ende habe ich ein Tool zum Nachbearbeiten der XML-Dokumentationsdateien erstellt, um Unterstützung für das Ersetzen des <inheritdoc/>Tags in den XML-Dokumentationsdateien selbst hinzuzufügen . Verfügbar unter www.inheritdoc.io (kostenlose Version verfügbar).

Nun, es gibt eine Art native Lösung, die ich für .NET Core 2.2 gefunden habe

Die Idee ist, <include>Tag zu verwenden .

Sie können hinzufügen <GenerateDocumentationFile>true</GenerateDocumentationFile>Ihre .csprojDatei.

Möglicherweise haben Sie eine Schnittstelle:

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

Und etwas, das davon erbt:

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, es ist ein bisschen beängstigend, aber es fügt die erwarteten Elemente hinzu YourNamespace.xml.

Wenn Sie bauen DebugKonfiguration können Sie tauschen Releasefür Debugim fileAttribut - includeTag.

Um eine korrekte zu finden member‚s namenur offen erzeugt Referenz - Documentation.xmlDatei.

Ich gehe auch davon aus, dass für diesen Ansatz ein Projekt oder eine Lösung mindestens zweimal erstellt werden muss (zum ersten Mal, um eine erste XML-Datei zu erstellen, und zum zweiten Mal, um Elemente daraus in sich selbst zu kopieren).

Die gute Seite ist, dass Visual Studio kopierte Elemente validiert, sodass es viel einfacher ist, Dokumentation und Code mit der Schnittstelle / Basisklasse usw. synchron zu halten (z. B. Namen von Argumenten, Namen von Typparametern usw.).

Bei meinem Projekt habe ich sowohl <inheritdoc/>(für DocFX) als auch <include/>(für die Veröffentlichung von NuGet-Paketen und für die Validierung in Visual Studio) Folgendes erreicht :

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