In diesem Thread wollte ich eine, evtl. schon bekannte, gute Möglichket der Programmdokumentation beschreiben, die auf Quellcode-Kommentaren von .Net Anwendungen basiert und im Look einer Standart .Net-Dokumentation erscheint.
Dokumentation warum?
In vielen Unternehmen scheint mir, aufgrund enormen Zeitdrucks bei der Entwicklung kleinerer Anwendungen, keine Dokumentation-Pflicht zu bestehen. Daher stellt sich natürlich die Frage warum Dokumentieren.
Die Antwort ist Simpel:
Wenn man als Entwickler bei der Entwicklung einer Anwendung darauf bedacht ist zu den Klassen, Felder, Attributen und Methoden Kommentare vor deren Implentierung zu schreiben, sollten Designprobleme, wie eine Methode mit 5 Parametern von denen 3 zu 99% mit null belegt werden, vorzeitig erkennbar sein.
Ausserdem erleichtert eine solche Annhährung an ein Problem meistens nicht den Blick für das große Ganze zu verlieren. Somit ist der Quellcode leicht verständlich und wenn man selbst oder ein anderer eine modifizierung des Programms vornehmen soll, kann dies schon nach kurzem Einlesen ohne IDE erfolgen.
Wie wirds gemacht?
Zunächste ich wichtig, dass man alle nötigen XML-QuellCode Kommentare setzt. Die gehschiet, wenn man den Cursor über Beispielsweise eine Mehtode setzt und dann 3 mal "/" ohne " schreibt. In Visual-Studio wird damit für einen kommentierungsrelevanten Teil ein abschnit mit den nötigen XML-Tags erzeugt. Dieser muss dann zwischen den Tags mit Sinn gefüllt werden.
Bei den Eigenschaften des Projekts im Projektmappenexplorer (Rechtsklick auf das entsprechende Projekt und dann "Eigenschaften") kann man dann unter dem Karteireiter "Erstellen" die Checkbox "XML Dokumentatiosdatei" aktivieren und einen Ausgabe Pfad bestimmen.
Die Umwandlung erfolgt dann mittels eines Zusatzprogramms "Sandcastle"
zu finden unter:
Sandcastle - Documentation Compiler for Managed Class Libraries
Dies ist ein Komandozeile basieretes Projekt das mittels Reflektion und der XML Dokumentationsdatei eine tolle Dokumentation aufbereitet.
Um nicht in alter Dosmanier alle Parameter per Komandozeile anzuhängen gibts die GUI Lösung in Verbingung mit oben genannten Sandcastle:
(Sandcastle Help File Builder)
Sandcastle Help File Builder
Letzten Endes kommentiert Ihr einfach den Quellcode erzeugt beim Buildvorgang wie obenbeschrieben die XML-Doku und erstellt eine neues "Sandcastle Help File Builder" Projekt, bei dem Ihr Eure Projektdatei unter "Documentation Sources" angebt und führt den Buildvorgang für das "Sandcastle Help File Builder" Projekt aus.
Ein gutes schnelles Tutorium haben die auch (bezieht sich auf das erstellen der Helpfile ... nach Installation der Software (die Links oben) und Kommentierung des Quellcodes des eigen Projektes)
http://www.ewoodruff.us/shfbdocs/html/