Jürgen Bayer XML- und HTML-Dokumentation mit C#
Inhaltsverzeichnis 1 Einleitung 1 2 Die XML-Dokumentation 2 2.1 Kompilieren 2 2.2 Vordefinierte XML-Elemente 4 3 Umwandeln der XML-Dokumentation in eine lesbare Form 7 3.1 Ein cooles Tool 7 3.2 HTML-Dokumentation über Sharp Develop 10 3.3 HTML-Dokumentation über Visual Studio 11 4 Index 12
Mit den speziellen Dokumentationskommentaren von C# können Sie sehr einfach eine XML-Dokumentation erzeugen, die Sie mit Visual Studio oder externen Tools in eine professionelle HTML-Dokumentation transformieren können. Damit können Sie Ihre Programme ganz einfach gleichzeitig kommentieren und dokumentieren. Dokumentationskommentare werden mit drei Schrägstrichen eingeleitet. Mit diesen Kommentaren können Sie alle Typen (Klassen, Strukturen, Aufzählungen etc.) und deren Elemente (Methoden, Eigenschaften, Ereignisse) dokumentieren. Innerhalb der Kommentare können Sie einfachen Text und XML-Elemente unterbringen. Über XML-Elemente können Sie eine eigene XML-Struktur aufbauen. Ein XML-Element summary kann z. B. eine zusammenfassende Beschreibung einer Methode enthalten, ein XML-Element param beschreibt die einzelnen Argumente der Methode. Die folgende einfache Klasse (die in einer Klassenbibliothek angelegt ist) enthält einige Dokumentationskommentare, die die Klasse und deren Member beschreiben: using System; namespace JB.Samples.Documentation /// Verwaltet die Grunddaten einer Firma public class Company /// Der Name der Firma public string CompanyName; /// Der Standort public string City; /// Die Strasse public string Street; Einleitung 1
Wenn Sie das Programm mit dem Kommandozeilencompiler kompilieren, geben Sie im Argument /doc an, in welche Datei die XML-Dokumentation erzeugt werden soll: csc /out:bin\jb.samples.documentation.dll /target:library /doc:bin\jb.samples.documentation.xml Company.cs Wenn Sie den Quellcode mit Sharp Develop (www.icsharpcode.net/opensource/sd/default.asp) kompilieren, schalten Sie in den Projektoptionen (die Sie über das PROJEKT-Menü erreichen) die Option XML DOKU GENERIEREN ein. Sie finden diese Option im Ordner KONFIGURATIONEN. Wenn Sie die Assemblierung erzeugen, generiert Sharp Develop automatisch eine XML-Datei mit dem Namen der Assemblierung. In Visual Studio geben Sie die Dokumentationsdatei in den Projekteigenschaften an. Wählen Sie dazu im Kontextmenü des Projekteintrags im Projekt-Explorer den Befehl EIGENSCHAFTEN. Stellen Sie den Dateinamen unter KONFIGURATIONSEIGENSCHAFTEN / ERSTELLEN / DOKUMENTATIONSDATEI ein. Beachten Sie, dass Sie diese Einstellung für jede Konfiguration (Debug, Release) einzeln vornehmen müssen. Sinnvoll ist allerdings in der Praxis nur die Einstellung für das Release, damit Visual Studio beim Testen der Anwendung in der Debug-Konfiguration nicht immer wieder die XML-Datei neu erzeugt. Wenn Sie das Projekt erstellen oder mit (F5) starten, wird die Dokumentationsdatei automatisch erzeugt. Nach dem Erstellen der Assembly sollten Sie sich in Visual Studio auf jeden Fall die Aufgabenliste anschauen. Dort führt Visual Studio alle öffentlichen Klassen(elemente) auf, bei denen die Dokumentation unvollständig ist und alle fehlerhaften Dokumentationen. Die XML-Dokumentation 2
Die Darstellung der erzeugten XML-Datei im Internet Explorer zeigt Abbildung 2.1. Abbildung 2.1: Eine Dokumentations-XML-Datei im Internet Explorer Die Dokumentation enthält einige Zeichen, die das Element näher beschreiben.»t«steht z. B. für»type«,»m«steht für»method«. In meinen Augen ist dies nicht konsequent XML-like: Warum haben die Entwickler nicht einfach ein Attribut des member-tags dafür verwendet (z. B: <member type="t" name="jb.samples.documentation">)? Tabelle 1 zeigt die verwendeten Typenzeichen. Zeichen N T F P M E Gehört zu Namensraum Typ (Klasse, Struktur, Aufzählung etc.) Feld Eigenschaft (Property) Methode Ereignis! Fehler. Der Compiler konnte einige Referenzen nicht auflösen. Das Element enthält eine Fehlerbeschreibung. Tabelle 1: Die Typenzeichen der XML-Dokumentation Die XML-Dokumentation 3
Für die Dokumentation können Sie beliebige XML-Elemente verwenden. Visual Studio schlägt Ihnen zwar einige Elemente vor, wenn Sie die spitze Klammer nach den drei Schrägstrichen schreiben, Sie können aber auch eigene Elemente einfügen. Die vordefinierten Elemente besitzen aber eine festgelegte Bedeutung. Tabelle 2 zeigt einige wichtige Elemente. Element <c>...</c> oder <code>...</code> <example> Beispiel </example> <para> Text </para> <param name="name"> Beschreibung </param> <paramref name="name"/> Parametername </paramref> <remarks> Bemerkungen </remarks> <returns> Beschreibung </returns> <see cref="element"> [Linktext] </see> Bedeutung Dieses Element verwenden Sie innerhalb von anderen Elementen, wenn Sie Teile des Textes als Quellcode kennzeichnen wollen (so wie ich es in diesem Artikel mit allen Schlüsselwörtern gemacht habe). Element, in dem Sie ein Beispiel, z. B. für den Aufruf einer Methode geben. NDoc übernimmt den hier angegebenen Text unter der Überschrift Example. Mit diesem Element können Sie den Text innerhalb eines anderen Elements in Absätze (Paragraphs) strukturieren. Beschreibung eines Parameters (Arguments) einer Methode Mit diesem Element können Sie ein Wort innerhalb eines Textes als Parameter einer Methode kennzeichnen. Bemerkungen zu einem Typ oder Element wie z. B. Hinweise zur Benutzung einer Klasse. NDoc übernimmt den hier angegebenen Text unter der Überschrift Remarks. Beschreibung des Rückgabewerts einer Methode Verweis zu einem Bezeichner, der im aktuellen Programm gültig ist. Hier können Sie auf eigene Typen bzw. Elemente (Methoden, Eigenschaften etc.) oder auf Typen des.net-frameworks verweisen. <seealso cref="element"/> Verweis ähnlich <see>, der allerdings in den Siehe auch -Bereich der Dokumentation eingetragen wird. <summary> Beschreibung </summary> <value> Zusammenfassende Beschreibung. NDoc übernimmt den hier angegebenen Text als Beschreibung der Klasse bzw. des Elements. Dieses Element beschreibt den Wert, den eine Eigenschaft repräsentiert (in der Regel, welches private Feld die Eigenschaft zur Speicherung des Datums verwendet). NDoc übernimmt den hier angegebenen Text unter der Überschrift Property Value. Tabelle 2: Die wichtigen vordefinierten XML-Elemente für eine XML-Dokumentation Eine vollständige Auflistung der vordefinierten XML-Elemente finden Sie in der.net-online- Hilfe. Suchen Sie im Index nach»xml documentation«bzw.»xml-dokumentation«. Im Internet ist das die Seite msdn.microsoft.com/library/enus/csref/html/vcorixmldocumentation.asp. Die XML-Dokumentation 4
Der folgende Quellcode verwendet die wichtigsten der XML-Elemente für Dokumentationen: using System; using System.Collections; namespace JB.Samples.Documentation /// Klasse für die Daten eines Mitarbeiters /// <remarks> /// <para> /// In den Eigenschaften <see cref="id"/>, /// <see cref="firstname"/> und /// <see cref="lastname"/> verwaltet diese /// Klasse die Daten des Mitarbeiters. /// </para> /// <para> /// Die Methode <see cref="getprojects"/> /// liefert eine Referenz auf die aktuellen /// Projekte des Mitarbeiters. /// </para> /// </remarks> /// <example> /// <code> /// Employee employee = /// new Employee(1001, "Donald", "Duck"); /// ArrayList projects = employee.getprojects(); /// for (int i = 0; i < projects.count; i++) /// /// Console.WriteLine( /// ((Project)projects[i]).Name); /// /// </code> /// </example> public class Employee private int id; /// Die Id des Mitarbeiters /// <value>diese Eigenschaft speichert /// ihren Wert im privaten Feld id</value> public int Id set if (value >= 0) this.id = id; else throw new ArgumentException( "Die Id muss ein Wert größer " + "als 0 sein", "Id"); get return this.id; /// Der Vorname des Mitarbeiters public String FirstName; /// Der Nachname des Mitarbeiters public String LastName; Die XML-Dokumentation 5
/// Konstruktor /// <param name="id"> /// Die ID des Mitarbeiters</param> /// <param name="firstname"> /// Der Vorname des Mitarbeiters</param> /// <param name="lastname"> /// Der Nachname des Mitarbeiters</param> /// <remarks> /// <para> /// In den Argumenten /// <paramref name="firstname" /> /// und <paramref name="lastname" /> /// übergeben Sie den Namen des Mitarbeiters. /// </para> /// <para> /// Beachten Sie ebenfalls den Konstruktor /// <see cref="employee()" /> /// </para> /// </remarks> public Employee(int id, String firstname, String lastname) this.id = id; this.firstname = firstname; this.lastname = lastname; /// Parameterloser Konstruktor /// <remarks> /// <para> /// Beachten Sie ebenfalls den Konstruktor /// <see cref="employee(int, String, String)" /> /// </para> /// </remarks> public Employee() this.id = 0; this.firstname = null; this.lastname = null; /// Liefert eine Auflistung der aktuellen /// Projekte des Mitarbeiters /// <returns> /// Gibt eine Referenz auf ein ArrayList-Objekt /// mit den aktuellen Projekten des Mitarbeiters /// zurück /// </returns> /// <remarks> /// Diese Methode ist noch nicht implementiert /// </remarks> public ArrayList GetProjects() throw new NotImplementedException(); Die XML-Dokumentation 6
! "# Bei der Adresse ndoc.sourceforge.net finden Sie den Download von NDoc, einem Tool, über das Sie aus der XML-Dokumentation automatisch eine sehr professionelle les- und durchsuchbare Dokumentation erzeugen können. Dieses Tool liegt als Installationsversion und im (komplexen) Quellcode vor und ist auf den ersten Blick ein wenig undurchsichtig (die Entwickler haben direkt mehrere Versionen erzeugt nur eine minimale Dokumentation beigelegt). Zur Erzeugung einer Dokumentation verwenden Sie idealerweise zunächst die GUI-Variante, die Sie im Ordner bin/<.net-framework-version> unter dem Namen NDocGui.exe finden. Wenn Sie mit diesem Programm ein NDoc-Projekt erzeugt haben, können Sie später die Konsolenanwendung NDocConsole.Exe zur Neu-Erzeugung der Dokumentation verwenden. Erzeugen Sie über csc.exe oder Visual Studio zunächst eine XML-Dokumentation. In NDoc geben Sie dann in einem neuen Projekt (das automatisch erzeugt wird) die Assemblierung und die XML-Datei an, indem Sie den ADD-Schalter betätigen. Umwandeln der XML-Dokumentation in eine lesbare Form 7
Abbildung 3.1: NDoc zur Erzeugung einer Dokumentation Speichern Sie dann das NDoc-Projekt über PROJECT / SAVE, idealerweise in den Ordner, in dem die XML- Datei abgelegt ist. Das Speichern des Projekts ist deswegen wichtig, da sich die Einstellung in der Option DOCUMENTATION MAIN SETTINGS / OUTPUTDIRECTORY bei einem gespeicherten Projekt auf den Projektordner bezieht, wenn es sich um eine relative Pfadangabe handelt. Haben Sie ein neues Projekt nicht gespeichert, bezieht sich eine relative Pfadangabe hingegen auf das Verzeichnis, in dem NDocGui.exe ausgeführt wird. Stellen Sie in der Option DOCUMENTATION MAIN SETTINGS / HTMLHELPNAME gegebenenfalls einen anderen Namen als den voreingestellten Namen Documentation ein. Den Wert in der Option Title sollten Sie ebenfalls anpassen. Diese Einstellungen variieren je nach Dokumentationstyp. Umwandeln der XML-Dokumentation in eine lesbare Form 8
In der Liste DOCUMENTATION TYPE können Sie eine der verfügbaren Typen für die Dokumentation wählen. Hier können Sie u. A. zwischen einer MSDN-ähnlichen, einer JavaDoc-ähnlichen Dokumentation und einer Dokumentation in XML-Form mit XSLT wählen. Achten Sie darauf, dass die Option DOCUMENTINTERNALS eingeschaltet ist, wenn Sie auch interne Typen und Elemente dokumentieren wollen. Optional können Sie zudem auch private und geschützte Typen dokumentieren. NDoc meldet einen Fehler, wenn keine dieser Optionen eingeschaltet ist und Ihr Projekt keine öffentlichen (public) Typen enthält. Sie müssen die Optionen (z. B. den Speicherort und die Einstellung, welche Typen dokumentiert werden sollen) für jede der Dokumentations-Varianten separat einstellen. Wenn Sie nun (Strg) (Shift) (B) betätigen, wird die Dokumentation in dem Ordner, den Sie in der Option OUTPUTDIRECTORY angegeben haben, erzeugt. Eine erzeugte HTML-Help-Dokumentation öffnen Sie über die nach Ihren Vorgaben benannte.chm-datei, eine erzeugte HTML-Dokumentation über die entsprechende.html-datei. Abbildung 3.2 zeigt eine aus dem obigen Beispiel erzeugte HTML-Help-Dokumentation. Abbildung 3.2: Eine mit NDoc erzeugte MSDN-HTML-Dokumentation Umwandeln der XML-Dokumentation in eine lesbare Form 9
Beachten Sie, dass HTML-Help scheinbar einige Probleme mit langen Pfadangaben hat. Auf meinem System behauptet HTML-Help beim Öffnen einer Hilfe aus einem längeren Pfad (G:\Manuskripte\Artikel\C#\XML-und-HTML-Dokumentation\Beispiele\doc\Msdn) beim Öffnen der einzelnen Hilfethemen, dass diese nicht existieren würden. Kopieren Sie in diesem Fall die Hilfedateien in einen Ordner mit einem kürzeren Pfad. Abbildung 3.3 zeigt eine mit NDoc erzeugte JavaDoc-Dokumentation. Abbildung 3.3: Eine mit NDoc erzeugte JavaDoc-HTML-Dokumentation $#% &'( In Sharp Develop können Sie ebenfalls HTML-Dokumentationen erzeugen. Sharp Develop nutzt dazu allerdings einfach NDoc (das als Klassenbibliothek integriert ist) Erzeugen Sie zunächst eine XML- Dokumentation und wählen Sie dann den Befehl PROJEKT / DOKUMENTATION GENERIEREN. Der Rest entspricht dem Vorgehen beim Erstellen einer Dokumentation über NDoc. Umwandeln der XML-Dokumentation in eine lesbare Form 10
$#% & In Visual Studio können Sie eine (leider recht mäßige ) HTML-Dokumentation über das Menü EXTRAS / ERSTELLEN VON KOMMENTARWEBSEITEN erzeugen. Achten Sie dabei auf den Speicherort, den Sie im Erstellen-Dialog angeben müssen. Abbildung 3.4 zeigt die aus dem Beispiel erzeugte Dokumentation. Abbildung 3.4: Eine mit Visual Studio erzeugte HTML-Dokumentation Visual Studio dokumentiert leider auch die privaten Elemente und scheint keine Möglichkeit zu bieten, diese wegzulassen. Außerdem werden leider (anders als bei NDoc in einer MSDNähnlichen Dokumentation) see- und seealso-referenzen nicht aufgelöst, wie Sie in Abbildung 3.4 erkennen können. Das value-element wird ebenfalls nicht berücksichtigt. Eigentlich ist diese Art der Dokumentation also nicht zu gebrauchen. Umwandeln der XML-Dokumentation in eine lesbare Form 11
) *+ Dokumentation 7 HTML-Dokumentation 7 NDoc 7 Typenzeichen in XML-Dokumentation 3 XML-Dokumentation Typenzeichen 3 umwandeln über NDoc 7 Vordefinierte XML-Elemente 4 Index 12