Home > Programmieren > Dokumentation für .NET-Klassen

Dokumentation für .NET-Klassen

4. August 2007

Das Erstellen einer Dokumentation und die ständige Aktualisierung speziell für .NET-Klassenbibliotheken sind sehr mühsam. Gleichzeitig sollen natürlich andere Programmierer die diese Klassenbibliothek verwenden im Klaren sein, welche Methoden, Eigenschaften,… die beinhalteten Klassen besitzen und was sie machen. Daher kann man bereits im Code über die XML-Kommentare kurze Erklärungen anbieten. Über den Objekt-Explorer bzw. IntelliSense von Visual Studio lassen sich diese dann auch abrufen, wenn nur eine kompilierte Version vorliegt.

Doch es geht auch besser. Die beim Kompilieren von Visual Studio exportierten XML-Dokumentationsdatei (Muss in den Projekteigenschaften im Register Erzeugen aktiviert sein.) enthält eigentlich bereits alles um daraus eine vollwärtige Dokumentation – die der MSDN Library ähnlich ist – zu erzeugen.

Leider hat Microsoft unverständlicherweise diese Funktionalität nicht in Visual Studio integriert. Deshalb wurde das freie Projekt NDoc (Ähnlich wie im Java-Universum JDoc.) in’s Leben gerufen. Allerdings wurde es bereits seit langer Zeit nicht mehr aktualisiert, da es eingestellt wurde. (NDoc 1.3.1 stammt noch vom 25.01.2005)

Eine Alternative auf die man setzen sollte ist Microsoft Sandcastle, das allerdings nur über die Konsole funktioniert. Dafür lässt sich mit Hilfe der XML-Dokumentationsdatei eine HTML-Hilfe, CHM-Dateien (Kompilierte HTML-Hilfedatei) und sogar die von der MSDN Library verwendeten HxS-Dateien erzeugen. Da Microsoft in der aktuellen Version allerdings immer noch keine grafische Oberfläche anbieten kann, gibt es einige kostenlose Projekte die dieses Problem beseitigen wollen.

Ich persönlich verwende das ebenfalls kostenlose Programm Codeplex Sandcastle Help File Builder. Es bietet eine einfache grafische Oberfläche ähnlich wie NDoc für Sandcastle und unterstützt auch das Zusammenfassen von mehreren XML-Dokumentationsdateien in eine einzige Dokumentation.

Alles was man also braucht ist Microsoft Sandcastle, Codeplex Sandcastle Help File Builder und natürlich die XML-Dokumentationsdatei aus dem kompilierten Visual Studio Projekt. Öffentlich sichtbare Klassen und deren Member sollten dabei natürlich unbedingt entsprechend per XML-Kommentare dokumentiert werden. Nur so kann später ein gutes Ergebnis erzielt werden.

  1. chmav
    16. September 2007, 10:29 | #1

    Hallo
    Hast du einen Tip für ein Tool um die XML-Kommentare zu erzeugen?

    Gruss Christoph

  2. 16. September 2007, 12:09 | #2

    @chmav:
    Wie oben beschrieben muss natürlich das Erzeugen der XML-Dokumentationsdatei in den Projekteigenschaften aktiviert sein.

    Die Eingabe muss man schon manuell mit den XML-Kommentaren (///) machen:

    ///< summary>Das ist meine Klasse< /summary>
    public class MyClass { ... }

    Eine Dokumentation dazu ist in der MSDN zu finden.

    Es gibt aber auch das Plugin GhostDoc mit dem sich automatisch XML-Kommentare erzeugen lassen. Damit lassen sich wiederkehrende lästige Aufgaben automatisieren.

Kommentare sind geschlossen