Trennzeichen für Visual C++-Dokumentationstags

  • Artikel

Die Verwendung von Dokumentationstags erfordert Trennzeichen, die für den Compiler angeben, wo ein Dokumentationskommentar beginnt und endet.

Sie können die folgenden Arten von Trennzeichen mit den XML-Dokumentationstags verwenden:

Trennzeichen Beschreibung
/// Dies ist das Formular, das in Dokumentationsbeispielen gezeigt und von den Visual Studio C++-Projektvorlagen verwendet wird.
/** */ Dies sind mehrzeilige Trennzeichen.

Für die Verwendung von /** */-Trennzeichen gibt es einige Formatierungsregeln:

  • Bei der Zeile, die das /** Trennzeichen enthält, wenn der Rest der Zeile Leerzeichen ist, wird die Zeile nicht für Kommentare verarbeitet. Wenn das erste Zeichen Leerzeichen ist, wird dieses Leerzeichen ignoriert und der Rest der Zeile verarbeitet. Andernfalls wird de gesamte Text der Zeile nach dem /**-Trennzeichen als Teil des Kommentars verarbeitet.

  • Bei der Zeile, die das */ Trennzeichen enthält, wird diese Zeile ignoriert, wenn nur Leerzeichen bis zum */ Trennzeichen vorhanden sind. Andernfalls wird der Text in der Zeile bis zum */-Trennzeichen als Teil des Kommentars verarbeitet, gemäß den Mustervergleichsregeln, die im folgenden Aufzählungszeichen beschriebenen werden.

  • Für die Zeilen nach dem Zeilen, die mit dem /** Trennzeichen beginnen, sucht der Compiler am Anfang jeder Zeile nach einem allgemeinen Muster, das aus optionalem Leerzeichen und einem Sternchen (*) besteht, gefolgt von optionalen Leerzeichen. Wenn der Compiler mehrere übereinstimmende Zeichen am Anfang jeder Zeile findet, wird das Muster für alle Zeilen nach dem /**-Trennzeichen ignoriert, bis zu und ggf. einschließlich der Zeile, die das */-Trennzeichen enthält.

Beispiele

  • Der einzige Teil des folgenden Kommentars, der verarbeitet wird, ist die Zeile, die mit <summary> beginnt. Die folgenden zwei Tagformate erzeugen die gleichen Kommentare:

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

  • Der Compiler wendet ein Muster von „*“ an, um den Anfang der zweiten und dritten Zeile zu ignorieren.

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

  • Der Compiler findet in diesem Kommentar kein Muster, da in der zweiten Zeile kein Sternchen vorhanden ist. Der gesamte Text in der zweiten und dritten Zeile wird bis zum */Ablauf 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 mit einer konsistenten Anzahl von Leerzeichen vor dem Sternchen beginnt. Zweitens beginnt die fünfte Zeile mit einem Tab, der mit Leerzeichen nicht übereinstimmt. Der gesamte Text aus der zweiten Zeile bis zum */ Verarbeiten des Kommentars.

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

Siehe auch

XML-Dokumentation