This post originated from an RSS feed registered with .NET Buzz
by -.
Original Post: Code-Dokumentation einfach gemacht!
Feed Title: Norbert Eder - Living .NET
Feed URL: http://feeds.feedburner.com/NorbertEder-Livingnet
Feed Description: Copyright (c)2005, 2006 by Norbert Eder
Die Dokumentation des Sourcecodes ist ein wichtiger - aber leider oft vernachlässigter - Bestandteil der Softwareentwickler. Vor allem Frameworks wollen gut dokumentiert werden, damit ein beliebiger Entwickler sofort damit loslegen kann, ohne sich lange einarbeiten zu müssen.
Nun ist es so, dass Visual Studio hier nicht besonders viel mitbringt. Lediglich das Schreiben der Kommentare in XML-Files, die später via IntelliSense eingebunden werden. Ein Tool zur Generierung von Hilfe-Dateien wird nicht über die IDE zur Verfügung gestellt. Aber es gibt auch andere Lösungen.
Benötigte Tools/Frameworks
Bevor mit der Generierung der Sourcecode-Dokumentation gestartet werden kann, müssen einige Frameworks/Tools installiert werden. Zentraler Bestandteil für diese Variante ist Sandcastle. Hier nun eine Liste der zu installierenden Produkte:
Hinweise: Der HTML Help Workshop ist nur für die Generierung von HTML 2.x Dokumentationen notwendig und muss nur installiert werden, wenn sich dieser noch nicht auf dem Rechner befindet.
Installation
Die ersten beiden Produkte kommen jeweils als MSI-Pakete daher. Daher sind diese sehr einfach in der Installation. Der HTML Workshop kann normal herunter geladen werden und muss nur in der Projekt-Konfiguration im Sandcastle Help File Builder in der Eigenschaft HtmlHelp2xCompilerPath angegeben werden. Nun noch GhostDoc installieren und schon ist man fast fertig.
Vorarbeiten
Wichtig ist, dass beim Build-Prozess XML-Kommentare ebenfalls generiert werden. Dazu ist die Einstellung in den Eigenschaften der jeweiligen Assemblies unter dem Punkt Build zu setzen.
Nun müssen natürlich auch noch sämtliche Kommentare geschrieben werden. Um sich viel Arbeit zu ersparen kann nun GhostDoc eingesetzt werden. Dieses unterstützt bei der Generierung der Dokumentation und liefert auch Vorschläge, die in einigen Fällen noch weiter angepasst werden müssen, aber grundsätzlich ist damit eine solide Basis geschaffen.
Generierung der Dokumentation
Mit Hilfe der Sandcastle Help File Builder GUI kann nun auf einfache Art und Weise ein Dokumentations-Projekt angelegt werden. Hierzu sind die notwendigen Assemblies anzugeben. Die vorhandenen XML-Dateien werden automatisch hinzugeladen und müssen daher nicht extra angegeben werden.
Wurden nun beispielsweise Frameworks á la NUnit, NLog etc. verwendet wird der Builder beim Ausführen beanstanden, dass referenzierte Assemblies nicht gefunden werden können. Anstatt diese über Add hinzuzufügen, empfiehlt es sich, diese im Builder unter Dependencies einzupflegen.
Nun müssen noch Einstellungen getroffen werden, welche Templates für Generierung verwendet werden, ob 1.x, 2.x generiert werden soll, oder gar eine Website und viele weitere Einstellungen wie Überschriften usw.
Ein wichtiger Punkt ist unter Namespaces zu finden: Hier ist es möglich einzustellen, welche Namespaces in der Dokumentation aufscheinen und es kann zusätzlich eine Beschreibung für diese eingegeben werden.
Wurde alles konfiguriert, kann die Generierung gestartet werden. Diese dauert zwar ein wenig länger als man erwartet, dafür ist das Ergebnis (vorausgesetzt es wurde brav dokumentiert) sehr fein und kann für die Weitergabe oder interne Verwendung herangezogen werden.
Fazit
Mit Hilfe dieser wenigen Tools und ca. 10 - 15 Minuten Installation und Konfiguration kann ein komplettes Dokumentations-System aufgesetzt werden. Die Dokumentation selbst kann uns leider niemand abnehmen, aber das soll keine Ausrede sein. Ich persönlich setze obige Kombination schon länger ein und bin bis dato sehr zufrieden.
Sicherlich wird es Möglichkeiten geben, dies weiter zu verbessern, wer hier also eine andere Konfiguration einsetzt bzw. Vorteile für seine Lösung anbieten kann, der sei hiermit eingeladen, mir dies mitzuteilen. Ebenfalls würde mich interessieren, ob ihr Code-Dokumentationen schreibt, oder nicht, inklusive einer kurzen Begründung.
Previous Topic
;)
;)