15.5 XML-Dokumentation 

In C# lässt sich der Programmcode bereits innerhalb des Codeeditors dokumentieren. Dazu werden XML-Tags in spezielle Kommentarfelder des Quellcodes eingefügt, die unmittelbar vor dem Codeblock stehen, auf den sie sich beziehen. Auf diese Weise können Typen wie Klassen, Enumerationen, Delegates, Schnittstellen und Strukturen sowie deren Eigenschaften, Felder, Methoden, Ereignisse usw. beschrieben werden.
Der Clou bei der XML-Dokumentation ist, den Code mit zusätzlichen Informationen zu versorgen, die sowohl in der IntelliSense-Hilfe, als auch im Objektkatalog nachzulesen sind. Darüber hinaus lässt sich die XML-Dokumentation auch in XML-Dateien veröffentlichen. Die XML-Dokumentationsdateien ersetzen sicherlich nicht eine konventionelle und aufwendige Dokumentation, können aber dennoch zumindest unterstützend bei der Entwicklung hilfreich sein.
15.5.1 Prinzip der XML-Dokumentation 

Nehmen wir zu Demonstrationszwecken die Methode GetArea der Klasse Circle, die wir dokumentieren möchten:
public static double GetArea(int radius) { return Math.PI * Math.Pow(radius, 2); }
XML-Dokumentationen werden dem Element vorangestellt, das dokumentiert werden soll. Eingeleitet werden die Kommentarfelder mit drei Schrägstrichen. Wenn Sie den Cursor vor das zu dokumentierende Element positionieren und die drei einleitenden Schrägstriche in den Code vor eine Klassendefinition schreiben, wird der folgende XML-Kommentar automatisch ergänzt:
/// <summary> /// /// </summary> /// <param name="radius"></param> /// <returns></returns>
Zwischen dem ein- und ausleitenden <summary>-Tag können Sie eine Beschreibung eintragen, die später vom zu generierenden XML-Dokument übernommen wird. Zudem wird die Beschreibung in der IntelliSense-Hilfe und im Objektkatalog angezeigt. Die Beschreibung zwischen <summary> und </summary> sollte kurz gehalten werden. Für ausführlichere Beschreibungen steht Ihnen mit <remarks> ein geeigneteres Tag zur Verfügung.
Sie können sehen, dass über <summary> hinaus noch weitere vordefinierte XML-Dokumentationstags angeboten werden. Das Attribut name des <param>-Tags enthält den Bezeichner des Parameters. Zwischen dem ein- und ausleitenden Tag dürfen Sie auch eine spezifische Beschreibung eintragen. Diese wird vom späteren XML-Dokument übernommen und im Objektkatalog angezeigt, allerdings nicht in IntelliSense. <returns> dient zur Beschreibung des Rückgabewertes. Für dieses Tag gilt hinsichtlich der Anzeige dasselbe wie für <param>.
Sehen wir uns an dieser Stelle einmal einen etwas aufwendigeren XML-Kommentar sowie dessen Auswirkungen an:
/// <summary>
/// Berechnet die Fläche eines beliebigen Kreises
/// </summary>
/// <param name="radius">Geben Sie hier den Radius des zu
berechnenden Kreises an
/// </param>
/// <returns>Liefert die Kreisfläche</returns>
/// <remarks>Die Methode ist 'static' definiert.
/// <para>Sie müssen diese Methode auf dem Klassenbezeichner aufrufen.
/// </para>
/// </remarks>
public static double GetArea(double radius) {
return Math.PI * Math.Pow(radius, 2);
}
Mit dem Objektkatalog, der über das Menü Ansicht geöffnet wird, können Sie Objekte (Namespaces, Klassen, Strukturen, Schnittstellen, Typen, Enumerationen usw.) und ihre Member (Eigenschaften, Methoden, Ereignisse, Variablen, Konstanten, Enumerationselemente) aus verschiedenen Komponenten suchen und überprüfen. Bei diesen Komponenten kann es sich um Projekte in der Projektmappe, um referenzierte Komponenten innerhalb dieser Projekte und um externe Komponenten handeln.
Schauen Sie sich im Objektkatalog nun die Ausgabe zu der Methode GetArea an (siehe Abbildung 15.22).
Abbildung 15.22 Ausgabe des XML-Kommentars im Objektkatalog
Ich glaube, dass Sie auch ohne eine langatmige Beschreibung erkennen können, welche Bereiche den einzelnen Tags zugeordnet werden. Im Codeeditor hingegen wird nur die Beschreibung angezeigt, die hinter <summary> angegeben ist (siehe Abbildung 15.23).
Abbildung 15.23 Anzeige der XML-Dokumentinformationen im Codeeditor
15.5.2 XML-Kommentar-Tags 

Ich habe Ihnen bisher einige, aber nicht alle Tags vorgestellt, die zur XML-Dokumentation dienen. In Tabelle 15.6 stelle ich Ihnen alle der Übersicht halber vor.
XML-Dokumentations-Tag | Beschreibung |
<c> |
Kennzeichnet, dass dieser Text in einer Beschreibung als Code erscheinen soll. |
<code> |
Kennzeichnet, dass mehrere Zeilen als Code dargestellt werden sollen. |
<example> |
Kennzeichnet ein Beispiel zur Verwendung einer Klasse oder Methode. |
<exception> |
Wird zur Dokumentation der Ausnahmen verwendet, die von einer Klasse ausgelöst werden können. |
<include> |
Mit diesem Tag kann auf Kommentare in anderen Dateien verwiesen werden, die die Typen und Member im Quellcode beschreiben. |
<list> |
Kennzeichnet eine Liste von Elementen. |
<para> |
Dieses Tag ist für die Verwendung innerhalb eines Tags, wie beispielsweise <summary>, <remarks> und <returns>, vorgesehen und ermöglicht die Strukturierung des Texts. |
<param> |
Dieses Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um einen der Parameter der Methode zu beschreiben. Der Text wird in IntelliSense und im Objektkatalog über Codekommentare angezeigt. |
<paramref> |
Ein Verweis auf einen anderen Parameter |
<permission> |
Wird zur Beschreibung der Zugriffsberechtigungen für ein Member verwendet. |
<remarks> |
Eine Beschreibung des Elements, die <summary> ergänzt. Die Informationen werden im Objektkatalog angezeigt. |
<returns> |
Dokumentiert den Rückgabewert einer Methode. |
<see> |
Wird zum Querverweis auf verwandte Elemente verwendet. |
<seealso> |
Eine Verknüpfung zum »Siehe auch«-Abschnitt der Dokumentation |
<summary> |
Eine kurze Beschreibung des Elements, die in IntelliSense und im Objektkatalog angezeigt wird |
<typeparam> |
Dieses Tag sollte in dem Kommentar für einen generischen Typ oder eine Methodendeklaration zum Beschreiben eines Typparameters verwendet werden. Fügen Sie für jeden Typparameter des generischen Typs oder der Methode ein Tag hinzu. |
<typeparamref> |
Der Name des Typparameters |
<value> |
Beschreibt den Wert einer Eigenschaft. |
15.5.3 Generieren der XML-Dokumentationsdatei 

Die Typen und deren Member mit XML-Kommentar zu versehen reicht zwar schon aus, um im Objektkatalog oder in der IntelliSense-Hilfe den Benutzer mit grundlegenden Informationen zu versorgen, aber damit wird nicht sofort ein XML-Dokument erzeugt, das sich beispielsweise zu einer Integration in eine Hilfe eignet und durchaus auch noch weitere Informationen bereitstellen kann.
Um aus den XML-Kommentaren eine XML-Dokumentationsdatei zu erzeugen, müssen Sie das Projekteigenschaftsfenster öffnen. Doppelklicken Sie dazu auf den Knoten Properties. Am linken Rand sind mehrere Laschen gruppiert; klicken Sie hier auf Erstellen (siehe Abbildung 15.24). Auf der nun angezeigten Registerkarte setzen Sie ein Häkchen neben XML-Dokumentationsdatei. Damit ist alles Notwendige erledigt. Die Vorgabe des Ausgabeordners und den Bezeichner der XML-Dokumentationsdatei können Sie im Bedarfsfall auch ändern.
Wir sollten auch einen Blick in das erzeugte Dokument werfen. Das gesamte Dokument wird in <doc>-Tags eingefasst. <doc> umfasst neben der Bekanntgabe des Dokumentationsnamens in <assembly> im Bereich <members> auch alle Tags, die wir im Codeeditor aufgeführt haben.
<?xml version="1.0"?> <doc> <assembly> <name>CircleApplication6</name> </assembly> <members> <member name="M:CircleApplication.Circle. GetFlaeche(System.Double)"> <summary> Berechnet die Fläche eines beliebigen Kreises </summary> <param name="radius">Geben Sie hier den Radius des zu berechnenden Kreises an </param> <returns>Liefert die Kreisfläche</returns> <remarks>Die Methode ist als 'static' definiert. <para>Sie müssen diese Methode auf dem Klassenbezeichner aufrufen. </para> </remarks> </member> </members> </doc>
Abbildung 15.24 So stellen Sie die Erzeugung eines XML-Dokumentationsdokuments ein.