17.5 XML-Dokumentation

In C# lässt sich der Programmcode bereits innerhalb des Code-Editors 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 IntelleSense-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 bei der Entwicklung hilfreich sein.

17.5.1 Das Prinzip der XML-Dokumentation

Nehmen wir zu Demonstrationszwecken die Methode GetArea der Klasse Circle, die wir dokumentieren möchten:

public static double GetFlaeche(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 den Klassenbezeichner aufrufen.
/// </para>
/// </remarks>
public static double GetFlaeche(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 17.9).

Abbildung 17.9 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 Code-Editor hingegen wird nur die Beschreibung angezeigt, die hinter <summary> angegeben ist (siehe Abbildung 17.10).

Abbildung 17.10 Anzeige der XML-Dokumentinformationen im Code-Editor

17.5.2 Die XML-Kommentartags

Ich habe Ihnen bisher einige, aber nicht alle Tags vorgestellt, die zur XML-Dokumentation dienen. In Tabelle 17.5 stelle ich Ihnen alle der Übersicht halber vor.

17.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 rechten Rand sind mehrere Laschen gruppiert; klicken Sie hier auf Erstellen (siehe Abbildung 17.11). 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.

Abbildung 17.11 Das Erzeugen eines XML-Dokumentationsdokuments einstellen

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 Code-Editor 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 'static' definiert.
    <para>Sie müssen diese Methode auf den Klassenbezeichner aufrufen.
    </para>
    </remarks>
    </member>
  </members>
</doc>

Listing 17.5 Inhalt der XML-Dokumentationsdatei

Ihre Meinung

Wie hat Ihnen das Openbook gefallen? Wir freuen uns immer über Ihre Rückmeldung. Schreiben Sie uns gerne Ihr Feedback als E-Mail an kommunikation@rheinwerk-verlag.de.