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.
c#
documentation
xml-documentation
Valentin Vasilyev
quelle
quelle
<inheritdoc/>
ist in Visual Studio kaputt. Bitte stimmen Sie für den Fehlerbericht unter visualstudio.uservoice.com/forums/121579-visual-studio/…Antworten:
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.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).
quelle
<inheritdoc/>
die Dokumentation für das<param>
Tag nicht geerbt wird .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
(verwendetCtrl-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.
quelle
Normalerweise schreibe ich Kommentare wie diese:
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.
quelle
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.quelle
Ich habe eine bessere Antwort: FiXml . Ich bin einer seiner Autoren
Das Klonen funktioniert zwar, funktioniert aber erheblich, z. B.:
Wie bereits erwähnt, gibt es
<inheritdoc>
in Sandcastle ein Tag , das jedoch im Vergleich zu FiXml nur wenige Nachteile aufweist:.xml
Dateien mit extrahierten XML-Kommentaren geändert (dies kann während der Kompilierung nicht "on the fly" durchgeführt werden).<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:
<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 .
quelle
Lies hier
Benutze das
quelle
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).
quelle
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.
quelle
Mit ReSharper können Sie es kopieren, aber ich glaube nicht, dass es die ganze Zeit synchron ist.
quelle