.NET XML-Dokumente - vererben Dokumentation

Question

NDoc hat ein XML-Element inheritdoc , die Sie Dokumentation ein Mitglied aus der übergeordneten Klasse erben kann (oder eine implementierte Schnittstelle). Jedoch Visual Studio (das heißt der C # -Compiler) dieses Tag nicht verstehen, und beschwert sich über die Dokumentation nicht vorhanden oder nicht vollständig. Das Gleiche gilt für StyleCop und einige andere Werkzeuge. Gibt es einen alternativen Ansatz? Wie gehen Sie über die Dokumentation vollständig zu halten, ohne jedoch die XML-Beschreibungen zu duplizieren?

Answer 1

Eine Alternative ist die Verwendung GhostDoc - ein Add-in für Visual Studio, die automatisch erzeugt Kommentare für Sie. Dies dupliziert die XML-Beschreibung natürlich, die einen Teil von dem, was Sie zu vermeiden, sind versucht, -. Aber zumindest tut es automatisch für Sie

Was passiert, wenn Sie nur die Dokumentation weglassen vollständig für Methoden, die vererbt werden oder übergeordnete Schnittstelle Methoden? Ich vermute, es hängt davon ab, wie Sie NDoc konfiguriert, aber sicher in MSDN-Dokumentation scheint nur natürlich die Dokumentation erben haben - und eine schnelle Überprüfung schlägt , dass VS nicht jammern, wenn Sie nicht prodive Dokumentation für eine vererbte Methode. Ein Versuch wert, sicher.

Answer 2

Ich habe eine bessere Antwort. FIXML

Cloning Kommentare mit GhostDoc arbeiten sicherlich Ansatz, aber es hat erhebliche Nachteile, z.B .:

• Wenn der ursprüngliche Kommentar geändert wird (die während der Entwicklung oft geschieht), seine Klon ist es nicht.
• Sie produzieren riesige Menge von Duplikaten. Wenn Sie mit irgend Source-Code-Analyse-Tools (z Duplicate Finder in Team-Stadt), wird es findet in erster Linie Ihre Kommentare.

Kurzbeschreibung von FIXML: Es ist ein Postprozessor von XML-Dokumentation von C # \ Visual Basic .NET erzeugt. Es ist, als MSBuild-Aufgabe implementiert, so ist es ganz einfach, es zu jedem Projekt zu integrieren. Es richtet sich einige lästige Fälle Schreiben XML-Dokumentation in diesen Sprachen bezogen werden:

• Keine Unterstützung für die Dokumentation von Basisklasse oder Schnittstelle vererben. D. h eine Dokumentation für jede überschriebene Mitglied sollte von Grund auf neu geschrieben werden, obwohl in der Regel ist es durchaus wünschenswert, zumindest den Teil davon zu übernehmen.
• Keine Unterstützung für das Einsetzen der am häufigsten verwendeten Dokumentationsvorlagen , wie „Diese Art Singleton ist -. Seine <see cref="Instance" /> Eigenschaft die einzige Instanz davon bekommen“, oder sogar „Initialisiert eine neue Instanz <CurrentType> Klasse“.

die oben genannten Probleme zu lösen, haben die folgenden zusätzlichen XML-Tags werden zur Verfügung gestellt:

• <inheritdoc />, <inherited /> Tags
• <see cref="..." copy="..." /> Attribut in <see/> Tag.

Hier ist seine Webseite und Download-Seite (defekte Links).

Schließlich gibt es <inheritdoc> Tag in Sandcastle - es ist auf jeden Fall besser zu verwenden, um es als XML-Kommentare zu kopieren, aber es hat einige Nachteile im Vergleich zu FIXML:

• Sandcastle produziert kompilierte HTML-Hilfedateien - es verändert nicht .xml Dateien mit den extrahierten XML-Kommentare. Aber diese Dateien werden von vielen Werkzeugen, einschließlich .NET Reflector und Klassenbrowser \ IntelliSense in Visual Studio .NET. Also, wenn Sie nur Sandcastle verwenden, werden Sie keine Dokumentation gibt geerbt sehen.
• Sandcastle-Implementierung ist weniger leistungsfähig. Z.B. das ist kein <see ... copy="true" />.

Siehe Sandcastle ist <inheritdoc> Beschreibung weitere Details.

Answer 3

Ich baute ein Kommandozeilen-Tool nachbearbeiten Dateien der XML-Dokumentation Unterstützung für den Tag hinzuzufügen.

Es hilft nicht, mit Intellisense im Quellcode aber es erlaubt in einem NuGet Paket den modifizierten XML-Dokumentationsdateien und daher mit Intellisense in referenzierten NuGet Paketen arbeitet aufgenommen werden.

Siehe www.inheritdoc.io für Details (kostenlose Version verfügbar).