Trennzeichen für Dokumentationstags (C#-Programmierhandbuch)

Aktualisiert: November 2007

Die Verwendung von XML-Dokumentkommentaren erfordert Trennzeichen, anhand derer der Compiler erkennt, wo ein Dokumentationskommentar anfängt und wo er aufhört. In Verbindung mit den XML-Dokumentationstags können die folgenden Trennzeichen verwendet werden:

• ///
  Diese Art Trennzeichen kommt in Dokumentationsbeispielen vor und wird in den Visual C#-Projektvorlagen verwendet.

  Hinweis:

  Die Visual Studio IDE verfügt über ein Feature mit der Bezeichnung Smart-Kommentar bearbeiten, durch das ein <summary>/</summary>-Tagpaar automatisch eingefügt und der Cursor innerhalb dieser Tags positioniert wird, nachdem Sie das ///-Trennzeichen im Code-Editor eingegeben haben. Greifen Sie auf dieses Feature in den Projekteigenschaftenseiten über Formatierung, C#, Text-Editor, Dialogfeld "Optionen" zu.

• /** */
  Mehrzeilige Trennzeichen.

Bei Verwendung der /** */-Trennzeichen sind einige Formatierungsregeln zu beachten:

• Wenn der verbleibende Teil der Zeile, in der das /** -Trennzeichen enthalten ist, ein Leerraum ist, wird die Zeile für Kommentare nicht verarbeitet. Wenn das erste Zeichen ein Leeraum ist, wird das entsprechende Zeichen ignoriert und der Rest der Zeile verarbeitet. Andernfalls wird der gesamte Zeilentext hinter dem /**-Trennzeichen als Teil des Kommentars verarbeitet.

• Wenn die Zeile, in der das */ -Trennzeichen enthalten ist, bis zum */-Trennzeichen nur Leerraum enthält, wird diese Zeile ignoriert. Andernfalls wird der Text in der Zeile bis zum */-Trennzeichen als Teil des Kommentars verarbeitet, wobei die im folgenden Punkt beschriebenen Mustervergleichsregeln gelten.

• Hinter der Zeile, die mit dem /**-Trennzeichen beginnt, überprüft der Compiler den Anfang der einzelnen Zeilen auf ein gemeinsames Muster. Dieses Muster besteht aus einem optionalen Leeraum und einem Sternchen (*), auf das mehrere optionale Leerräume folgen. Wenn der Computer am Anfang jeder Zeile eine gemeinsame Zeichengruppe findet, ignoriert er dieses Muster für alle Zeilen hinter dem /**-Trennzeichen, und zwar bis zu und möglicherweise auch einschließlich der Zeile, in der das */-Trennzeichen enthalten ist.

Einige Beispiele:

• Vom folgenden Kommentar wird nur die Zeile verarbeitet, die mit <summary> beginnt. Die folgenden beiden Tagformate ergeben identische Kommentare:

  /**

  <summary>text</summary>

  */

  /** <summary>text</summary> */

• Der Compiler wendet das Muster " * " an, das zu Beginn der zweiten und dritten Zeile ignoriert werden soll.

  /**

  * <summary>

  * text </summary>*/

• Der Compiler findet in diesem Kommentar kein Muster, da die zweite Zeile kein Sternchen enthält. Folglich wird der gesamte Text in der zweiten und dritten Zeile bis zum */-Trennzeichen als Teil des Kommentars verarbeitet.

  /**

  * <summary>

  text </summary>*/

• Der Compiler findet aus zwei Gründen kein Muster in diesem Kommentar. Zunächst gibt es keine Zeile, die vor dem Sternchen eine konsistente Anzahl von Leerzeichen enthält. Zweitens beginnt die fünfte Zeile mit einem Tabulatorzeichen, das sich von Leerzeichen unterscheidet. Folglich wird der gesamte Text von der zweiten Zeile bis zum */-Trennzeichen als Teil des Kommentars verarbeitet.

  /**

  * <summary>

  * text

  * text2

  * </summary>

  */

Siehe auch

Aufgaben

Beispiel für die XML-Dokumentation

Konzepte

C#-Programmierhandbuch

Referenz

XML-Dokumentationskommentare (C#-Programmierhandbuch)

/doc (Dokumentationskommentare verarbeiten) (C#-Compileroptionen)

XML-Dokumentationskommentare (C#-Programmierhandbuch)