Kommentare zur XML-Dokumentation mit Schnittstellen und Implementierungsklasse (n)

Question

Ich dokumentiere eine Assembly mit XML Documentation Comments, von der eine chm Datei mit Sandcastle erstellt wird.

Meine Assembly enthält verschiedene Schnittstellen, von denen jede von einer Klasse implementiert wird (in meinem Szenario sind dies WCF-Dienste).

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

Answer 1

Es scheint keine Unterstützung für solche Autodokumentation in Sandcastle zu geben. Die Sandcastle Help File Builder implementiert jedoch ein benutzerdefiniertes inseritdoc-Tag.

Vom SHFB Website:

Unterstützung für die < inheritdoc/> Tag enthalten, die Sie vererben Dokumentation von Basis Typen/Mitglieder erlaubt. Dies wird über ein eigenständiges Tool implementiert, so dass es auch von anderen Drittanbieter-Tools und Build-Skripten verwendet werden kann. Dieses Tool bietet Funktionen, die über die in der Buildkomponente, die mit Sandcastle geliefert wird, gefundenen Features hinausgehen.

Zweite Update: nach this workitem, die Sandcastle "Unterstützung" für inheritdoc ist durch das SHFB Werkzeug. Fazit: Ich nehme an, SHFB löst Ihr Problem.

Answer 2

Ein Tool wie GhostDoc kann die Dokumentation zu den implementierenden Klassen generieren, wenn Sie die Tastenkombination verwenden. Das ist nicht völlig automatisch, könnte aber helfen, zu viel Kopieren zu verhindern.

Vielleicht könnte es mit einem Skript automatisiert werden.

Answer 3

AtomineerUtils generiert automatisch Kommentare für Sie, und die vorhandene Dokumentation wird aus Überladungen und überschriebenen Basisklassen übernommen. So sparen Sie sich die Mühe, die Informationen dort zu duplizieren, wo sie gebraucht werden.

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

Answer 4

Ich habe eine bessere Antwort: FIXML.

Klonen Kommentare mit GhostDoc \ AtomineerUtils sicherlich Ansatz funktioniert, aber es hat erhebliche Nachteile, z.B .:

• Wenn der ursprüngliche Kommentar geändert wird (die häufig während der Entwicklung geschieht), seinen Klon nicht.
• Sie produzieren eine große Menge an Duplikaten. Wenn Sie Quellcodeanalyse-Tools verwenden (z. B. Duplicate Finder in Team City), finden Sie unter hauptsächlich 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 enthält extrahierte XML-Kommentare. Aber diese Dateien werden von vielen Tools, einschließlich .NET Reflector und Klassenbrowser \ IntelliSense in Visual Studio .NET verwendet. Wenn Sie also nur Sandcastle verwenden, sehen Sie dort keine vererbte Dokumentation.
• Die Implementierung von Sandcastle ist weniger leistungsstark. Z.B. Das ist kein <see ... copy="true" />.

Weitere Details finden Sie unter Sandcastle's <inheritdoc> description.

Kurze Beschreibung von FiXml: Es ist ein Postprozessor der XML-Dokumentation, die von C# \ Visual Basic .Net erzeugt wird. Es ist als MSBuild-Task implementiert, so dass es sehr einfach ist, es in jedes 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 erben. I.e. Eine Dokumentation für jedes überschriebene Mitglied sollte von Grund auf neu geschrieben werden, obwohl es normalerweise wünschenswert ist, zumindest den Teil davon zu erben.
• Keine Unterstützung für das Einsetzen der am häufigsten verwendeten Dokumentationsvorlagen, wie „diese Art ist Singleton -. Verwendet seine <see cref="Instance" /> Eigenschaft die einzige Instanz davon zu bekommen“, oder sogar „Initialisiert eine neue Instanz der <CurrentType> Klasse.“

genannten Probleme zu lösen, haben die folgenden zusätzlichen XML-Tags versehen sind:

• <inheritdoc />, <inherited /> Tags
• <see cref="..." copy="..." /> attrib ute in tag.

Hier ist its web page und download page.