Ograniczniki tagów dokumentacji visual C++

  • Artykuł

Użycie tagów dokumentacji wymaga ograniczników, które wskazują kompilatorowi, w którym rozpoczyna się i kończy komentarz dokumentacji.

Można użyć następujących rodzajów ograniczników z tagami dokumentacji XML:

Ogranicznik opis
/// Jest to formularz przedstawiony w przykładach dokumentacji i używany przez szablony projektów programu Visual Studio C++.
/** */ Są to ograniczniki wielowierszowe.

W przypadku używania /** */ ograniczników istnieją pewne reguły formatowania:

  • W przypadku wiersza zawierającego /** ogranicznik, jeśli pozostała część wiersza jest białym znakiem, wiersz nie jest przetwarzany dla komentarzy. Jeśli pierwszy znak jest białym znakiem, znak biały jest ignorowany, a reszta wiersza jest przetwarzana. W przeciwnym razie cały tekst wiersza po przetworzeniu /** ogranicznika w ramach komentarza.

  • W przypadku wiersza zawierającego */ ogranicznik, jeśli jest tylko biały znak do */ ogranicznika, ten wiersz jest ignorowany. W przeciwnym razie tekst w kolejce do */ ogranicznika jest przetwarzany jako część komentarza, z zastrzeżeniem reguł dopasowywania wzorców opisanych w poniższym punkcie.

  • W przypadku wierszy po tym, który zaczyna się /** od ogranicznika, kompilator szuka wspólnego wzorca na początku każdego wiersza, który składa się z opcjonalnego odstępu i gwiazdki (*), a następnie więcej opcjonalnych białych znaków. Jeśli kompilator znajdzie wspólny zestaw znaków na początku każdego wiersza, zignoruje ten wzorzec dla wszystkich wierszy po ograniczniku /** , maksymalnie do i ewentualnie w tym wiersz, który zawiera */ ogranicznik.

Przykłady

  • Jedyną częścią następującego komentarza, który zostanie przetworzony, jest wiersz rozpoczynający się od <summary>. Następujące dwa formaty tagów będą tworzyć te same komentarze:

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

  • Kompilator stosuje wzorzec " * " do ignorowania na początku drugiego i trzeciego wiersza.

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

  • Kompilator nie znajduje wzorca w tym komentarzu, ponieważ w drugim wierszu nie ma gwiazdki. Cały tekst w drugim i trzecim wierszach do momentu przetworzenia */elementu w ramach komentarza.

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

  • Kompilator nie znajduje wzorca w tym komentarzu z dwóch powodów. Po pierwsze, nie ma wiersza rozpoczynającego się od spójnej liczby spacji przed gwiazdką. Po drugie piąty wiersz zaczyna się od karty, która nie pasuje do spacji. Cały tekst z drugiego wiersza do */ momentu przetworzenia elementu w ramach komentarza.

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

Zobacz też

Dokumentacja XML