XML-Dokumentation Kommentare mit Schnittstellen und Implementierungsklasse (n) [geschlossen]

Question

Ich bin dokumentieren eine Baugruppe mit XML Kommentare zur Dokumentation , von denen eine chm Datei wird unter Verwendung erstellt werden Sandcastle .

Meine Baugruppe enthält verschiedene Schnittstellen, von denen jeder durch eine Klasse implementiert ist (in meinem Szenario sind diese WCF-Dienste).

Ich habe Dokumentation zu den Schnittstellen hinzugefügt, gibt es eine Möglichkeit für mich, automatisch die entsprechenden Methoden zu den Durchführungs Klassen zu dokumentieren?

Answer 1

Es scheint nicht für solche autodocumentation in Sandcastle jede Unterstützung. Die Sandcastle Help File Builder obwohl implementiert eine benutzerdefinierte inheritdoc-Tag.

Von der SHFB Website:

  

Support ist für die eingeschlossen    Tag, das Ihnen erlaubt,   erben Dokumentation von der Basis   types / Mitglieder. Dies erfolgt über   sein ein eigenständiges Tool, so kann es auch   von anderen Tools von Drittanbietern verwendet und   Build-Skripte. Dieses Tool bietet   über jene Merkmale in die gefunden   Aufbau Komponente geliefert mit   Sandburg.

Zweites Update: nach diesem workitem , sind die Sandburg „Träger“ für inheritdoc durch das SHFB Werkzeug. Unterm Strich Ich nehme an ist, SHFB Ihr Problem löst.

Answer 2

Ich habe eine bessere Antwort. FIXML

Cloning Kommentare mit GhostDoc \ AtomineerUtils ist sicherlich arbeiten 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.

Wie es erwähnt wurde, gibt es <inheritdoc> Tag in Sandcastle , aber es einige Nachteile im Vergleich zu FIXML hat:

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

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 .

Answer 3

Ein Werkzeug wie GhostDoc können die Dokumentation über die Durchführungs Klassen generieren, Sie, wenn es die Tastenkombination verwenden. Das ist nicht ganz automatisch, sondern könnte dazu beitragen, zu viel Kopie Einfügen zu verhindern.

Vielleicht könnte es mit einem Skript automatisiert werden.

Answer 4

AtomineerUtils wird automatisch generieren Kommentare für Sie, und es nimmt von Überlastungen und außer Kraft gesetzter Basisklasse vorhandene Dokumentation, Sie jede Menge Ärger Speicher in den Informationen zu duplizieren, wo es gebraucht wird.

http://www.atomineer.com/AtomineerUtils.html