XML ファイルの処理 (C# プログラミング ガイド)
コンパイラは、ドキュメントを生成するためにタグ付けされたコードの構成体ごとに、ID 文字列を生成します。コードにタグを付ける方法については、「ドキュメント コメントとして推奨されるタグ」を参照してください。ID 文字列によって、構成体は一意に識別されます。XML ファイルを処理するプログラムは、ID 文字列を使用して、ドキュメントの適用対象となる .NET Framework メタデータ/リフレクション項目を識別できます。
XML ファイルは、コードの階層的表現ではなく、要素ごとに生成された ID のあるフラットなリストです。
コンパイラは、次の規則に基づいて ID 文字列を生成します。
空白は含めません。
ID 文字列の最初の部分には、単一の文字とコロンで識別されるメンバーの種類を示します。使用されるメンバー型は次のとおりです。
文字
Description
N
namespace
名前空間にはドキュメント コメントを追加できませんが、サポートされている場合は、ドキュメント コメントへの cref 参照を作成できます。
T
型 : class、interface、struct、enum、delegate
F
field
P
プロパティ (インデクサーまたはその他のインデックス付きプロパティを含む)
M
メソッド (コンストラクター、演算子などの特殊なメソッドを含む)
E
event
!
エラー文字列
エラーに続く文字列で、エラーの内容を示します。C# コンパイラは、解決できないリンクについてのエラー情報を生成します。
文字列の 2 番目の部分は、項目の完全限定名です。名前は、名前空間のルートから始まります。項目の名前、項目が含まれている型、および名前空間は、ピリオドで区切られます。名前自体にピリオドがある場合、名前のピリオドはハッシュ記号 ('#') に置き換えられます。項目の名前にはハッシュ記号がないことが前提です。たとえば、String コンストラクターの完全限定名は、"System.String.#ctor" になります。
プロパティおよびメソッドについては、メソッドに引数がある場合は、引数のリストをかっこで囲み、メソッドに続けて指定します。引数がない場合は、かっこはありません。引数の区切り文字には、コンマを使用します。各引数のエンコードは、次に示す .NET Framework のシグネチャでの引数のエンコーディング方法にそのまま従います。
基本型。通常の型 (ELEMENT_TYPE_CLASS または ELEMENT_TYPE_VALUETYPE) は、型の完全限定名で表されます。
ELEMENT_TYPE_I4、ELEMENT_TYPE_OBJECT、ELEMENT_TYPE_STRING、ELEMENT_TYPE_TYPEDBYREF、ELEMENT_TYPE_VOID など、組み込みの型は、対応する完全な型の完全修飾名で表されます。たとえば、System.Int32 や System.TypedReference です。
ELEMENT_TYPE_PTR は、修飾される型に続けて '*' と表されます。
ELEMENT_TYPE_BYREF は、修飾される型に続けて '@' と表されます。
ELEMENT_TYPE_PINNED は、修飾される型に続けて '^' と表されます。C# コンパイラでは生成されません。
ELEMENT_TYPE_CMOD_REQ は、修飾される型に続けて "|" と修飾子クラスの完全限定名で表されます。C# コンパイラでは生成されません。
ELEMENT_TYPE_CMOD_OPT は、修飾される型に続けて "!" と修飾子クラスの完全修飾名で表されます。
ELEMENT_TYPE_SZARRAY は、配列の要素型に続けて "[]" と表されます。
ELEMENT_TYPE_GENERICARRAY は、配列の要素型に続けて "[?]" と表されます。C# コンパイラでは生成されません。
ELEMENT_TYPE_ARRAY は、[lowerbound:size,lowerbound:size] の形式で表されます。ここで、コンマの個数はランク -1 個であり、各次元の下限とサイズは明らかな場合は、10 進数で表されます。下限またはサイズを、指定しない場合は省略します。特定の次元で下限およびサイズが省略されている場合は、その次元の ':' も省略されます。たとえば、ある 2 次元配列の下限が 1 で、サイズの指定がない場合は、[1:,1:] と表されます。
ELEMENT_TYPE_FNPTR は、"=FUNC:type(signature)" と表されます。ここで、type は戻り値の型であり、signature はメソッドの引数です。引数がない場合は、かっこが省略されます。C# コンパイラでは生成されません。
次に示すシグネチャ コンポーネントは、オーバーロードされるメソッドの区別には使用されることがないため、表されません。
呼び出し規約
戻り値の型
ELEMENT_TYPE_SENTINEL
変換演算子 (op_Implicit および op_Explicit) だけは、上記のエンコードと同様に、メソッドの戻り値が '~' としてエンコードされ、それに続けて戻り値の型が表されます。
ジェネリック型では、型の名前の後に、バック チック (`)、ジェネリック型パラメーターの数を示す数値が順に続きます。次に例を示します。
<member name="T:SampleClass`2"> は、public class SampleClass<T, U> として定義されている型のタグです。
パラメーターとしてジェネリック型を受け取るメソッドでは、ジェネリック型パラメーターは、バック チック付きの数値 (`0、`1 など) として指定されます。各数値は、型のジェネリック パラメーターに対する、インデックス番号が 0 から始まる配列表記を表しています。
例
クラスおよびそのメンバーの ID 文字列が生成される例を次に示します。
namespace N
{
/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:N.X".
/// </summary>
public unsafe class X
{
/// <summary>
/// Enter description here for the first constructor.
/// ID string generated is "M:N.X.#ctor".
/// </summary>
public X() { }
/// <summary>
/// Enter description here for the second constructor.
/// ID string generated is "M:N.X.#ctor(System.Int32)".
/// </summary>
/// <param name="i">Describe parameter.</param>
public X(int i) { }
/// <summary>
/// Enter description here for field q.
/// ID string generated is "F:N.X.q".
/// </summary>
public string q;
/// <summary>
/// Enter description for constant PI.
/// ID string generated is "F:N.X.PI".
/// </summary>
public const double PI = 3.14;
/// <summary>
/// Enter description for method f.
/// ID string generated is "M:N.X.f".
/// </summary>
/// <returns>Describe return value.</returns>
public int f() { return 1; }
/// <summary>
/// Enter description for method bb.
/// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <param name="y">Describe parameter.</param>
/// <param name="z">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int bb(string s, ref int y, void* z) { return 1; }
/// <summary>
/// Enter description for method gg.
/// ID string generated is "M:N.X.gg(System.Int16[],System.Int32[0:,0:])".
/// </summary>
/// <param name="array1">Describe parameter.</param>
/// <param name="array">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int gg(short[] array1, int[,] array) { return 0; }
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Addition(N.X,N.X)".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <param name="xx">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static X operator +(X x, X xx) { return x; }
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.prop".
/// </summary>
public int prop { get { return 1; } set { } }
/// <summary>
/// Enter description for event.
/// ID string generated is "E:N.X.d".
/// </summary>
public event D d;
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.Item(System.String)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <returns></returns>
public int this[string s] { get { return 1; } }
/// <summary>
/// Enter description for class Nested.
/// ID string generated is "T:N.X.Nested".
/// </summary>
public class Nested { }
/// <summary>
/// Enter description for delegate.
/// ID string generated is "T:N.X.D".
/// </summary>
/// <param name="i">Describe parameter.</param>
public delegate void D(int i);
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Explicit(N.X)~System.Int32".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static explicit operator int(X x) { return 1; }
}
}
参照
関連項目
XML ドキュメント コメント (C# プログラミング ガイド)