programming/netfx/classlibrary/2_xmldoccomments/index.wiki.txt

--同一クラス内のメンバを参照する場合はクラス名を省略できる

--異なるクラスのメンバを参照する場合はクラス名から記述する必要がある

--using句・Importステートメントでインポートされていない名前空間の型を参照する場合は、名前空間を付加した完全限定名で型名を記述する必要がある

-オーバーロードされたメソッドでは、参照するメソッドを限定するために引数リストを記述する必要がある

-``List<T>``などのジェネリック型を参照する場合はXML中に山カッコを記述することはできないので、文字参照を使って``List&amp;lt;T&amp;gt;``と記述するか、波カッコを使って``List{T}``と記述する必要がある

これらの点を踏まえてcref属性を記述すると次のようになります。

#code(cs,cref属性の指定例){{

using System;

using System.Collections.Generic;

namespace SampleNamespace {

  struct Structure1 {

    int Field;

  }

  class Class1 {

    /// <example>

    /// 同一型内のメンバの場合は、クラス名を省略して<see cref="Field"/>や<see cref="Method"/>のように記述できる

    /// 異なる型のメンバの場合は、<see cref="Structure1.Field"/>のように型名から記述する必要がある

    /// </example>

    public int Field = 0;

    public void Method() {}

    /// <example>

    /// オーバーロードされたメソッドを限定する場合は、<see cref="Method1()"/>、

    /// <see cref="Method1(int)"/>、<see cref="Method1(int,int)"/>のように引数リストを記述する必要がある

    /// </example>

    public void Method1() {}

    public void Method1(int x) {}

    public void Method1(int x, int y) {}

    /// <example>

    /// 引数が配列やref/outパラメータの場合は、

    /// <see cref="Method1(int[,])"/>、<see cref="Method1(ref int)"/>のように記述する

    /// </example>

    public void Method1(int[,] x) {}

    public void Method1(ref int x) {}

    /// <example>

    /// コンストラクタを参照する場合は、<see cref="Class1()"/>、<see cref="Class1(int)"/>のように

    /// 「型名(引数リスト)」と記述する

    /// </example>

    public Class1() {}

    public Class1(int x) {}

  }

  /// <example>

  /// ジェネリック型・ジェネリックメソッドを参照する場合、

  /// 山カッコを文字参照に置き換えて<see cref="List&lt;T&gt;.Add"/>のように記述するか、

  /// 山カッコを波カッコに置き換えて<see cref="List{T}.Add"/>のように記述する必要がある

  /// <see cref="List{THoge}.Add"/>のように型パラメータ名が異なっていても、型パラメータの数が一致すれば適切に参照される

  /// </example>

  class Class2 {

    /// <exception cref="ArgumentException">インポートされた名前空間にある型は名前空間を記述しなくてもよい</exception>

    /// <exception cref="System.ComponentModel.InvalidEnumArgumentException">

    /// インポートされていない名前空間にある型は、完全限定名を記述する必要がある

    /// </exception>

    /// <remarks>実際にはスローされない例外がcref属性に記述されていてもエラーとはならない</remarks>

    public void ThrowsExceptionMethod()

    {

    }

  }

  /// <example>

  /// インポートされていない場合に完全限定名を記述するのは、型だけでなくメンバの場合も同様

  /// <see cref="OtherNamespace.Class5.Field5"/>

  /// </example>

  class Class3 {

    protected void Method3() {}

  }

  /// <example>

  /// 基底クラスのメンバを参照する場合は、<see cref="Class3.Method3()"/>のように型名から記述する必要がある

  /// </example>

  class Class4 : Class3 {

  }

}

namespace OtherNamespace {

  class Class5 {

    public static readonly int Field5 = 16;

  }

}

}}

このほか、cref属性では[[メンバのID>#xmlelement_memberid]]を指定することもできます。

***メンバのID [#xmlelement_memberid]

see要素などで指定されたcref属性の値は、コンパイル時に後述する形式のIDに変換されます。　例えば、次のようなXMLドキュメントが記述されているコードがあったとします。

#code(cs,cref属性を記述したXMLドキュメント){{

/// <seealso cref="String.IndexOf(string)"/>

class Class1 {}

}}

このコードをコンパイルすると、cref属性は次のように変換されます。

#code(xml,出力されるXMLドキュメントの抜粋){{

<member name="T:Class1">

    <seealso cref="M:System.String.IndexOf(System.String)" />

</member>

}}

このIDは、「&var{メンバの種類};:&var{完全限定名};」の形式で定義されています。　メンバの種類は一文字で表され、型を表す''T''やメソッドを表す''M''などを指定します。　例えば、型であれば「T:&var{名前空間};.&var{型名};」となり、メソッドであれば「M:&var{名前空間};.&var{型名};.&var{メソッド名};(&var{引数リスト};)」のようになります。　このように変換されるメンバのIDは、cref属性を指定する際にも使用することができます。

IDの規則といくつかの変換例を表にまとめると次のようになります。

**CDATAを使ったサンプルコードの記述

XMLドキュメントの要素中では不等号``<``,``>``を直接記述することができません。　かわりに文字参照(``&amp;lt;``, ``&amp;gt;``)に置き換えて説明文を記述することもできますが、比較演算子やジェネリック型を多用するサンプルコードを記述する場合には不便です。

CDATAセクションを使うと、次の例のように文字参照への置き換えなしでコードをそのまま記述することができます。

#code(cs,CDATAセクションを使ってサンプルコードを記述する例){{

using System;

using System.Collections.Generic;

/// <example>

///  CDATAセクションを使った<see cref="List{T}"/>のサンプルコード記述例です。

///  <code><![CDATA[

///    var list = new List<string>();

///

///    list.Add("foo");

///    list.Add("bar");

///

///    if (0 < list.Count)

///      list.Add("baz");

///  ]]></code>

///  文字参照を使った<see cref="List{T}"/>のサンプルコード記述例です。

///  <code>

///    var list = new List<string>();

///

///    list.Add("foo");

///    list.Add("bar");

///

///    if (0 < list.Count)

///      list.Add("baz");

///  </code>

/// </example>

class Class1 {}

}}

#code(xml,コンパイルして得られるXMLドキュメント){{

<member name="T:Class1">

     <example>

      CDATAセクションを使った<see cref="T:System.Collections.Generic.List`1"/>のサンプルコード記述例です。

      <code><![CDATA[

        var list = new List<string>();

        list.Add("foo");

        list.Add("bar");

        if (0 < list.Count)

          list.Add("baz");

      ]]></code>

      文字参照を使った<see cref="T:System.Collections.Generic.List`1"/>のサンプルコード記述例です。

      <code>

        var list = new List<string>();

        list.Add("foo");

        list.Add("bar");

        if (0 < list.Count)

          list.Add("baz");

      </code>

     </example>

</member>

}}

CDATAセクションはcode要素以外でも使うことができます。