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

98

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.

Valentin Vasilyev
quelle
Ist diese Funktion implementiert? visualstudio.uservoice.com/forums/121579-visual-studio/…
hellboy
Wie kann ich Atomineer Pro dazu bringen, das Dokumentations-Tag <inheritDoc /> für die Implementierung zu generieren, wenn Dokumentation für die Schnittstelle verfügbar ist?
Hellboy
3
Sie haben Recht, <inheritdoc/>ist in Visual Studio kaputt. Bitte stimmen Sie für den Fehlerbericht unter visualstudio.uservoice.com/forums/121579-visual-studio/…
Colonel Panic

Antworten:

62

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).

Noldorin
quelle
Hey, das ist ziemlich schön! Ich mag Sandcastle!
Tor Haugen
Beitrag bearbeitet, um aktualisierte Frage zu beantworten.
Noldorin
2
Kann dies auf Klassenebene durchgeführt werden? damit ich nicht vor jeder Methode /// <inheritdoc /> setzen muss.
Antony Scott
1
Eine Sache, die mir aufgefallen ist, ist, dass <inheritdoc/> die Dokumentation für das <param>Tag nicht geerbt wird .
Stephen
1
Stimmen Sie über diese Benutzerstimmfunktion ab, um <inheritdoc /> offiziell zur C # -Spezifikation hinzuzufügen,
tödlicher Hund
14

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 . Alt-Text

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.

Igal Tabachnik
quelle
Die neueste Version (5.3.16270) von GhostDoc kann auch geerbte Dokumente erstellen. Ich habe es gerade für meine Schnittstellenimplementierungen versucht. Netter Bonus, es fügt auch die Ausnahmen mit der Nachricht der ausgelösten Ausnahme hinzu :-)
Christoph
6

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.

Stefan Steinegger
quelle
4

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.

Tor Haugen
quelle
6
Persönlich mag ich GhostDoc nicht. Es wird eine Dokumentation generiert, in der es tatsächlich keine gibt. Dies verbirgt die Tatsache, dass etwas nicht dokumentiert ist. Nur eine persönliche Meinung, ich sage nicht, dass es im Allgemeinen etwas Schlechtes ist.
Stefan Steinegger
1
Stimmen Sie dem Kommentar von Stefan darin zu, dass GhostDoc nicht perfekt ist, zieht jedoch automatisch "geerbte" Kommentare wie diesen ein, sodass es eine ziemlich gute Antwort auf die Frage ist.
Steve
Stefan, ich bin anderer Meinung - im Gegenteil, da GhostDoc nur die Dokumentation widerspiegelt, die Sie bereits in Ihre Mitgliedsnamen "eingefügt" haben (indem Sie Prosa aus den Namen erstellen), generiert es nur Dokumentation, wenn bereits Dokumentation vorhanden ist (implizit). Als solches "produziert" es nichts, aber die generierte Prosa ist ein ausgezeichneter Ausgangspunkt, zu dem Sie einen tatsächlichen Wert hinzufügen können. Echte Dokumentation erfordert noch einige Arbeit.
Tor Haugen
2

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 .

Alex Yakunin
quelle
1

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).

K Johnson
quelle
0

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.

1800 INFORMATIONEN
quelle
3
Ich hätte die Schnittstelle hier nicht verwendet, wenn ich sie nicht in Tests vorgetäuscht hätte.
Valentin Vasilyev
0

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

Crauscher
quelle