Oddělovače pro značky dokumentace visual C++
Použití značek dokumentace vyžaduje oddělovače, které označují kompilátoru, kde začíná a končí komentář dokumentace.
U značek dokumentace XML můžete použít následující druhy oddělovačů:
Delimiter | Popis |
---|---|
/// |
Toto je formulář zobrazený v příkladech dokumentace a používaný šablonami projektů visual Studio C++. |
/** */ |
Jedná se o víceřádkové oddělovače. |
Při použití /** */
oddělovačů existují některá pravidla formátování:
Pokud je zbytek řádku prázdným znakem, řádek, který obsahuje
/**
oddělovač, se pro komentáře nezpracuje. Pokud je první znak prázdný, bude tento znak prázdného znaku ignorován a zbytek řádku se zpracuje. Jinak se celý text řádku za/**
oddělovačem zpracuje jako součást komentáře.Pro čáru
*/
, která obsahuje oddělovač, je-li pouze prázdné znaky až do*/
oddělovače, bude tento řádek ignorován. V opačném případě se text na řádku až do*/
oddělovače zpracuje jako součást komentáře s výhradou pravidel porovnávání vzorů popsaných v následující odrážce.Pro řádky za řádky, které začínají
/**
oddělovačem, kompilátor hledá společný vzor na začátku každého řádku, který se skládá z volitelného prázdného místa a hvězdičky (*
), následovaný volitelnými prázdnými znaky. Pokud kompilátor najde společnou sadu znaků na začátku každého řádku, bude ignorovat tento vzor pro všechny řádky za/**
oddělovačem, až do a případně i včetně řádku, který obsahuje*/
oddělovač.
Příklady
Jedinou částí následujícího komentáře, který bude zpracován, je řádek, který začíná
<summary>
na . Následující dva formáty značek vytvoří stejné komentáře:/** <summary>text</summary> */ /** <summary>text</summary> */
Kompilátor použije vzor * pro ignorování na začátku druhého a třetího řádku.
/** * <summary> * text </summary>*/
Kompilátor nenajde v tomto komentáři žádný vzor, protože na druhém řádku není hvězdička. Veškerý text na druhém a třetím řádku až do doby
*/
, než se zpracuje jako součást komentáře./** * <summary> text </summary>*/
Kompilátor nenajde v tomto komentáři žádný vzor ze dvou důvodů. Za prvé, neexistuje žádný řádek, který začíná konzistentním počtem mezer před hvězdičkou. Za druhé, pátý řádek začíná tabulátorem, který neodpovídá mezery. Veškerý text z druhého řádku, dokud
*/
nebude zpracován jako součást komentáře./** * <summary> * text * text2 * </summary> */