Visual C++ ドキュメント タグの区切り記号
ドキュメント タグでは "区切り記号" を使用し、ドキュメント コメントの開始位置と終了位置をコンパイラに示す必要があります。
XML ドキュメント タグでは、次の種類の区切り記号を使用できます。
| 区切り記号 | 説明 |
|---|---|
/// |
これは、ドキュメント例に示されている形式であり、Visual Studio C++ プロジェクト テンプレートで使用されます。 |
/** */ |
これらは複数行の区切り記号です。 |
/** */ 区切り記号を使用する場合は、次のいくつかの書式設定規則があります。
/**区切り記号がある行では、行の残りの部分が空白の場合、その行はコメントとして処理されません。 最初の文字が空白の場合、その空白文字は無視され、行の残りの部分が処理されます。 それ以外の場合、/**区切り記号の後にある行のテキスト全体が、コメントの一部として処理されます。*/区切り記号がある行では、*/区切り記号までの部分がすべて空白の場合、その行は無視されます。 それ以外の場合、以下の箇条書きで説明するパターン一致規則に従って、その行の*/区切り記号までのテキストがコメントの一部として処理されます。/**区切り記号で始まる行の後にある行では、コンパイラは各行の先頭で共通のパターンを検索します。このパターンは、空白 (省略可能) + アスタリスク (*) + 空白 (省略可能) で構成されます。 コンパイラは、各行の先頭で共通の文字セットを見つけた場合、/**区切り記号の後にあるすべての行のそのパターンを無視します。これらの行には、*/区切り記号がある行まで (その行を含む) が含まれることがあります。
例
次のコメントでは、
<summary>で始まる行だけがコメントの一部として処理されます。 次の 2 つのタグ形式では同じコメントが生成されます。/** <summary>text</summary> */ /** <summary>text</summary> */コンパイラは、2 行目と 3 行目の先頭で無視するために " * " というパターンを適用します。
/** * <summary> * text </summary>*/2 行目にはアスタリスクがないため、コンパイラはこのコメントでパターンを検出しません。
*/までの、2 行目と 3 行目のすべてのテキストは、コメントの一部として処理されます。/** * <summary> text </summary>*/コンパイラでは、2 つの理由により、このコメントのパターンが検出されません。 まず、各行のアスタリスクの前の空白の数が一致していません。 次に、5 行目がタブで始まっていて、空白と一致しません。 2 行目から
*/までのすべてのテキストはコメントの一部として処理されます。/** * <summary> * text * text2 * </summary> */