Möglichkeiten zum synchronisieren von Schnittstelle und Implementierung Kommentare in C#

Gibt es automatische Möglichkeiten zur Synchronisierung von Kommentaren zwischen einer Schnittstelle und Ihrer Implementierung?
Ich bin derzeit dokumentieren Sie beide und möchte das nicht manuell synchron zu halten.

UPDATE:

Betrachten Sie diesen code:

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

Wenn ich die Klasse erstellen wie diese:

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

Hier-Kommentare werden nicht angezeigt:

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

Den <inheritDoc/> tag wird perfekt generieren die Dokumentation in der Sandburg, aber es funktioniert nicht in der intellisense-QuickInfo.

Bitte teilen Sie Ihre Ideen.

Dank.

Hinzugefügt Dokumentation-tag
Ist diese Funktion implementiert? visualstudio.uservoice.com/forums/121579-visual-studio/...
Wie kann ich Atomineer Pro lassen generieren <inheritDoc/> Dokumentation-tag für die Umsetzung, wenn die Dokumentation für die Schnittstelle verfügbar ist?
Du hast Recht <inheritdoc/> ist gebrochen in Visual Studio. Bitte voten für den bug-report, unter visualstudio.uservoice.com/forums/121579-visual-studio/...

InformationsquelleAutor Valentin | 2009-05-05

c#documentation xml-documentation

56

Können Sie dies ganz einfach tun, mit dem Microsoft Sandcastle (oder NDoc) inheritdoc tag. Es ist nicht offiziell unterstützt, von der Spezifikation, aber benutzerdefinierte tags sind durchaus akzeptabel, und in der Tat entschied sich Microsoft zu kopieren (und ein oder zwei anderen tags) von NDoc, wenn Sie erstellt Sandburg.
```
///<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 Hilfe-Seite von der Sandcastle Help File Builder GUI, die beschreibt, seiner Nutzung in voller Höhe.

(Natürlich, dies ist nicht speziell die "synchronisation", wie Ihre Frage erwähnt, aber es scheint zu sein, genau das, was du suchst, aber trotzdem.)

Als Hinweis, das klingt wie eine perfekt gerechte Idee zu mir, obwohl ich beobachtet habe, dass einige Leute denken, Sie sollte immer neu einzugeben Kommentare in abgeleiteten und implementierten Klassen. (Ich habe es tatsächlich getan, es mir in der Dokumentation eine meiner Bibliotheken, und ich habe nicht sehen, keinerlei Probleme.) Es ist fast immer kein Grund für die Kommentare unterscheiden sich alle, warum also nicht einfach Erben und tun Sie es der einfache Weg?

Edit: Bezüglich Ihrer update, Sandburgen können auch aufpassen, für Sie. Sandcastle-Leistung eine modifizierte version der eigentlichen XML-Datei, die es verwendet für die Eingabe, das heißt, Sie können verteilen diese modifizierte version zusammen mit Ihrer Bibliothek, DLL, nicht die direkt von Visual Studio, was bedeutet, Sie haben die Kommentare in intellisense sowie der Dokumentation-Datei (CHM, was auch immer).

Hey, das ist schön! Ich mag Sandburgen!
Post bearbeitet zu beantworten aktualisierte Frage.
kann das getan werden, auf einem Klasse Niveau? so dass ich nicht haben, um setzen Sie /// <inheritdoc /> vor jeder Methode.
Eine Sache, die ich bemerkt habe, ist, dass <inheritdoc/> Erben nicht in der Dokumentation für die <param> tag.
Gehen-Abstimmung in dieser user-voice-Funktion zu haben <inheritdoc /> offiziell Hinzugefügt, um die C# - Spezifikationen und die Arbeit mit VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/...

InformationsquelleAutor Noldorin
11

Wenn Sie Sie nicht verwenden es bereits, ich empfehle ein freies Visual Studio-addon namens GhostDoc. Es erleichtert die Dokumentation Prozess. Haben Sie einen Blick auf mein Kommentar auf eine etwas Verwandte Frage stellen.

Obwohl GhostDoc nicht die Synchronisierung automatisch, kann es helfen, Sie mit dem folgenden Szenario:

Haben Sie ein dokumentiertes interface-Methode. Implementieren Sie dieses interface in eine Klasse, drücken Sie die GhostDoc Tastenkombination Ctrl-Shift-D, und der XML-Kommentar von der Schnittstelle Hinzugefügt werden, um die implementierte Methode.

Gehen Sie auf die Optionen -> Tastatur Einstellungen, und weisen Sie eine Taste, um GhostDoc.AddIn.RebuildDocumentation (ich habe Ctrl-Shift-Alt-D).

Nun, wenn Sie änderungen in der XML-Kommentar auf der Schnittstelle, nur drücken Sie diese Tastenkombination auf die implementierte Methode, und die Dokumentation wird aktualisiert. Leider funktioniert das nicht Umgekehrt.

Die neueste version (5.3.16270) von GhostDoc können auch vererbt Doku. Ich habe gerade versucht es für meine interface-Implementierungen. Netter bonus, es fügt auch die Ausnahmen mit der Meldung der ausgelösten Ausnahme 🙂

InformationsquelleAutor Igal Tabachnik
5

Schreibe ich normalerweise Kommentare wie diese:
```
///<summary>
///Implements <see cref="IMyInterface.Foo(string, int)"/>
///</summary>
///<returns></returns>
```
Methoden verwendet werden, die nur von der Schnittstelle, also in diesem Kommentar wird auch nicht angezeigt in den tooltips bei der Codierung.

Edit:

Wenn Sie möchten, um zu sehen, docs, wenn Sie rufen Sie die Klasse direkt und nicht Verwendung der Schnittstelle, die Sie schreiben müssen Sie zweimal oder verwenden Sie ein tool wie GhostDoc.

InformationsquelleAutor Stefan Steinegger
4

Versuchen GhostDoc! Es funktioniert für mich 🙂

Edit: Nun habe ich aufmerksam gemacht worden Sandcastle Unterstützung für <inheritdoc/> unterstütze Noldorin ' s post. Es ist eine viel bessere Lösung. Ich noch empfehlen, GhostDoc auf einer Allgemeinen basis, wenn.

Ich persönlich mag keine GhostDoc. It-Dokumentation erzeugt, wo es eigentlich keine. Dies ist die Tatsache verstecken, dass etwas nicht dokumentiert ist. Nur eine persönliche Meinung, ich sage nicht, dass es etwas ist schlecht im Allgemeinen.
Einverstanden mit dem Kommentar von Stefan, dass GhostDoc ist nicht perfekt, es ist aber nicht automatisch pull-in "geerbt" Kommentare wie diese, so ist es eine ziemlich gute Antwort auf die Frage.
Stefan, ich Stimme nicht zu - im Gegenteil, denn GhostDoc spiegelt lediglich die Unterlagen, die Sie habe bereits "gesetzt" in Ihrem Elementnamen (durch den Bau von Prosa, von den Namen), es erzeugt nur Dokumentation, Dokumentation existiert bereits (implizit). Als solche, es 'produziert' nichts, aber die erzeugte Prosa ist ein ausgezeichneter Ausgangspunkt, um die Sie hinzufügen können, ist-Wert. Echtzeit-Dokumentation dauert noch einige Arbeit.

InformationsquelleAutor Tor Haugen
2

Habe ich eine bessere Antwort: FiXml.

Klonen ist sicherlich Arbeitsweise, aber es hat erhebliche Nachteile, z.B.:
- Wenn die ursprünglichen Kommentar geändert wird (was oft geschieht während der Entwicklung),
  Klon ist nicht.
- Sie produzieren riesige Menge von Duplikaten. Wenn Sie eine
  source-code-Analyse-tools (z.B. Duplicate Finder im Team der Stadt), es wird
  finde vor allem deine Kommentare.
Wie es bereits erwähnt wurde, gibt es <inheritdoc> tag in Sandcastle, aber es hat einige Nachteile im Vergleich zu FiXml:
- Sandcastle erzeugt kompilierte HTML-Hilfe-Dateien - normalerweise ist es nicht ändern
  .xml - Dateien, extrahiert die XML-Kommentare (endlich, das kann nicht getan werden
  "on-the-fly" während der Kompilierung).
- Sandburg, die Umsetzung ist weniger leistungsfähig. E. g. das ist keine
  <see ... copy="true" />.
Sehen Sandcastle ' s <inheritdoc> Beschreibung für weitere details.

Kurze Beschreibung der FiXml: es ist ein post-Prozessor, der XML-Dokumentation, produziert von C# \ Visual Basic .Net. Implementiert ist es als MSBuild-task, so dass es Recht einfach zu integrieren in dieses Projekt. Es behebt einige lästige Fällen mit Bezug auf das schreiben von XML-Dokumentation in folgenden Sprachen:
- Keine Unterstützung für den Erben die Dokumentation aus der Basis-Klasse oder Schnittstelle. I. e. eine Dokumentation für alle überschriebenen Mitglied sollte von Grund auf neu geschrieben werden, obwohl normalerweise es ist sehr wünschenswert, um die Erben zumindest der Teil der es.
- Keine Unterstützung für das einfügen von Häufig verwendeten Dokumentation Vorlagen, wie "Dieser Typ ist singleton - den <see cref="Instance" /> - Eigenschaft, um die einzige Instanz von Ihr.", oder auch "Initialisiert eine neue Instanz der <CurrentType> Klasse."
Lösen genannten Themen, werden die folgenden zusätzlichen XML-tags werden zur Verfügung gestellt:
- <inheritdoc />, <inherited /> tags
- <see cref="..." copy="..." /> Attribut in <see/> tag.
Hier ist seine web-Seite und download-Seite.

Sollten Sie der Weitergabe Ihrer Zugehörigkeit FiXml.
Ja, das ist richtig - ich bin einer der Autoren. Vielen Dank für die Mitteilung von mir.
Link ist tot...

InformationsquelleAutor Alex Yakunin
1
```
///<inheritDoc/>
```
Lesen Sie hier

Verwenden Sie diese

InformationsquelleAutor Krzysztof Kozmic
1

Baute ich eine Bibliothek zum post-Prozess die Dokumentation zu XML-Dateien, um Unterstützung für den <inheritdoc/> - tag.

Während es nicht helfen, mit der Intellisense im source code, der es erlaubt, die geänderte XML-Dokumentation, die Dateien in ein NuGet-Paket und arbeitet daher mit Intellisense in der referenzierten NuGet-Pakete.

Weitere Infos unter http://www.inheritdoc.io (Kostenlose version verfügbar).

InformationsquelleAutor K Johnson
0

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

InformationsquelleAutor crauscher
-1

Nicht. Denken Sie an es auf diese Weise - wenn beide Kommentare sind erforderlich, um die gleiche die ganze Zeit, dann ist einer von Ihnen nicht notwendig. Es muss einen Grund für den Kommentar (neben einigen seltsamen Verpflichtung zur Kommentar-block, der jede Funktion und variable), so dass Sie brauchen, um herauszufinden, was, der einzige Grund ist und dokumentieren Sie das.

Ich hätte nicht verwendeten interface-hier hatte nicht ich wurde vorgetäuscht, in tests.

InformationsquelleAutor 1800 INFORMATION

Schreibe einen Kommentar

Du musst angemeldet sein, um einen Kommentar abzugeben.