Möglichkeiten zum Synchronisieren von Schnittstellen- und Implementierungskommentaren in C # [geschlossen]

Gibt es automatische Möglichkeiten, Kommentare zwischen einer Schnittstelle und ihrer Implementierung zu synchronisieren? Ich dokumentiere derzeit beide und möchte sie nicht manuell synchronisieren.

AKTUALISIEREN:

Betrachten Sie diesen Code:

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

Wenn ich eine Klasse wie diese erstelle:

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

Hier werden Kommentare nicht angezeigt:

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

Das <inheritDoc/>Tag generiert die Dokumentation in Sand Castle perfekt, funktioniert jedoch nicht in Intellisense-Tooltips.

Bitte teilen Sie Ihre Ideen.

Vielen Dank.

Sie können dies ganz einfach mit dem Microsoft Sandcastle (oder NDoc) inheritdoc-Tag tun . Es wird von der Spezifikation nicht offiziell unterstützt, aber benutzerdefinierte Tags sind durchaus akzeptabel, und Microsoft hat sich tatsächlich dafür entschieden, dieses (und ein oder zwei andere Tags) von NDoc zu kopieren, als sie Sandcastle erstellt haben.

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

Hier ist die Hilfeseite der Benutzeroberfläche von Sandcastle Help File Builder, auf der die Verwendung vollständig beschrieben wird.

(Natürlich ist dies nicht speziell "Synchronisation", wie in Ihrer Frage erwähnt, aber es scheint genau das zu sein, wonach Sie suchen.)

Als Hinweis klingt dies für mich nach einer vollkommen fairen Idee, obwohl ich festgestellt habe, dass einige Leute der Meinung sind, dass Sie Kommentare in abgeleiteten und implementierten Klassen immer neu spezifizieren sollten. (Ich habe es tatsächlich selbst gemacht, als ich eine meiner Bibliotheken dokumentiert habe, und ich habe überhaupt keine Probleme gesehen.) Es gibt fast immer keinen Grund, warum sich die Kommentare überhaupt unterscheiden. Warum also nicht einfach erben und es auf einfache Weise tun?

Bearbeiten: In Bezug auf Ihr Update kann Sandcastle dies auch für Sie erledigen. Sandcastle kann eine geänderte Version der tatsächlichen XML-Datei ausgeben, die für die Eingabe verwendet wird. Dies bedeutet, dass Sie diese geänderte Version zusammen mit Ihrer Bibliotheks-DLL anstelle der direkt von Visual Studio erstellten Version verteilen können. Dies bedeutet, dass Sie die Kommentare sowohl in Intellisense als auch in Intellisense haben die Dokumentationsdatei (CHM, was auch immer).

Wenn Sie es noch nicht verwenden, empfehle ich dringend ein kostenloses Visual Studio-Addon namens GhostDoc . Dies erleichtert den Dokumentationsprozess. Schauen Sie sich meinen Kommentar zu einer etwas verwandten Frage an.

Obwohl GhostDoc die Synchronisierung nicht automatisch durchführt, kann es Ihnen bei folgendem Szenario helfen:

Sie haben eine dokumentierte Schnittstellenmethode. Implementieren Sie diese Schnittstelle in einer Klasse, drücken Sie die GhostDoc-Tastenkombination Ctrl-Shift-D, und der XML-Kommentar von der Schnittstelle wird der implementierten Methode hinzugefügt.

Gehen Sie zu Optionen -> Tastatureinstellungen und weisen Sie GhostDoc.AddIn.RebuildDocumentation(verwendet Ctrl-Shift-Alt-D) eine Taste zu .

Wenn Sie nun den XML-Kommentar auf der Benutzeroberfläche ändern , drücken Sie einfach diese Tastenkombination für die implementierte Methode, und die Dokumentation wird aktualisiert. Leider funktioniert das nicht umgekehrt.

Normalerweise schreibe ich Kommentare wie diese:

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

Die Methoden werden nur von der Benutzeroberfläche verwendet, sodass dieser Kommentar beim Codieren nicht einmal in QuickInfos angezeigt wird.

Bearbeiten:

Wenn Sie Dokumente anzeigen möchten, wenn Sie die Klasse direkt aufrufen und die Schnittstelle nicht verwenden, müssen Sie sie zweimal schreiben oder ein Tool wie GhostDoc verwenden.

Probieren Sie GhostDoc ! Für mich geht das :-)

Bearbeiten: Nachdem ich auf Sandcastles Unterstützung aufmerksam gemacht wurde <inheritdoc/>, unterstütze ich Noldorins Beitrag. Es ist eine viel bessere Lösung. Ich empfehle GhostDoc jedoch weiterhin allgemein.

Ich habe eine bessere Antwort: FiXml . Ich bin einer seiner Autoren

Das Klonen funktioniert zwar, funktioniert aber erheblich, z. B.:

• Wenn der ursprüngliche Kommentar geändert wird (was häufig während der Entwicklung vorkommt), ist dies bei seinem Klon nicht der Fall.
• Sie produzieren eine große Anzahl von Duplikaten. Wenn Sie Quellcode-Analysetools verwenden (z. B. Duplicate Finder in Team City), werden hauptsächlich Ihre Kommentare gefunden.

Wie bereits erwähnt, gibt es <inheritdoc>in Sandcastle ein Tag , das jedoch im Vergleich zu FiXml nur wenige Nachteile aufweist:

• Sandcastle erstellt kompilierte HTML-Hilfedateien - normalerweise werden keine .xmlDateien mit extrahierten XML-Kommentaren geändert (dies kann während der Kompilierung nicht "on the fly" durchgeführt werden).
• Die Implementierung von Sandcastle ist weniger leistungsfähig. ZB ist das nein <see ... copy="true" />.

Siehe Sandcastle der <inheritdoc>Beschreibung für weitere Details.

Kurzbeschreibung von FiXml: Es handelt sich um einen Postprozessor für XML-Dokumentation, der von C # \ Visual Basic .Net erstellt wurde. Es ist als MSBuild-Aufgabe implementiert, sodass es recht einfach in jedes Projekt integriert werden kann. Es werden einige lästige Fälle im Zusammenhang mit dem Schreiben von XML-Dokumentation in diesen Sprachen behandelt:

• Keine Unterstützung für das Erben der Dokumentation von der Basisklasse oder der Schnittstelle. Das heißt, eine Dokumentation für ein überschriebenes Mitglied sollte von Grund auf neu geschrieben werden, obwohl es normalerweise durchaus wünschenswert ist, zumindest einen Teil davon zu erben.
• Keine Unterstützung für das Einfügen häufig verwendeter Dokumentationsvorlagen , z. B. "Dieser Typ ist Singleton - verwenden Sie seine <see cref="Instance" />Eigenschaft, um die einzige Instanz davon abzurufen." Oder sogar "Initialisiert eine neue <CurrentType>Klasseninstanz".

Um die genannten Probleme zu lösen, werden die folgenden zusätzlichen XML-Tags bereitgestellt:

• <inheritdoc />, <inherited /> Stichworte
• <see cref="..." copy="..." />Attribut im <see/>Tag.

Hier ist seine Webseite und Download-Seite .

/// <inheritDoc/>

Lies hier

Benutze das

Ich habe eine Bibliothek erstellt, um die XML-Dokumentationsdateien nachzubearbeiten und Unterstützung für das Tag <inheritdoc /> hinzuzufügen.

Es hilft zwar nicht mit Intellisense im Quellcode, ermöglicht jedoch die Aufnahme der geänderten XML-Dokumentationsdateien in ein NuGet-Paket und funktioniert daher mit Intellisense in NuGet-Paketen, auf die verwiesen wird.

Weitere Informationen unter www.inheritdoc.io (kostenlose Version verfügbar).

Tu das nicht. Stellen Sie sich das so vor - wenn beide Kommentare immer gleich sein müssen, ist einer von ihnen nicht erforderlich. Es muss einen Grund für den Kommentar geben (abgesehen von einer seltsamen Verpflichtung, jede Funktion und Variable zu blockieren), also müssen Sie herausfinden, was dieser eindeutige Grund ist, und dies dokumentieren.

Mit ReSharper können Sie es kopieren, aber ich glaube nicht, dass es die ganze Zeit synchron ist.