2013-08-05T23:17:15の更新内容

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

current previous
185,7 185,7
 
|~|~exception要素|<exception cref="&var{member};">...</exception>|{{
|~|~exception要素|<exception cref="&var{member};">...</exception>|{{
 
メンバがスローする例外に関する説明を記述します。
メンバがスローする例外に関する説明を記述します。
 

        

        
~
[[cref属性>#xmlelement_crefattribute]]でスローする例外の型を、要素のテキストでその例外がスローされる理由・状況についての説明を記述します。
cref属性でスローする例外の型を、要素のテキストでその例外がスローされる理由・状況についての説明を記述します。 cref属性の指定方法は[[メンバのID>#xmlelement_memberid]]で解説します。
 
}}|
}}|
 
|~|~example要素|<example>...</example>|{{
|~|~example要素|<example>...</example>|{{
 
型やメンバの使用例について記述します。
型やメンバの使用例について記述します。
196,10 196,10
 
|~|~seealso要素|<seealso cref="&var{member};"/>|{{
|~|~seealso要素|<seealso cref="&var{member};"/>|{{
 
指定されたメンバ&var{member};へのリンクを「参照」セクションの関連項目に追加します。
指定されたメンバ&var{member};へのリンクを「参照」セクションの関連項目に追加します。
 

        

        
~
seealso要素を使うことで、親クラスやオーバーロードされた他のメソッド、類似するメンバなどのリンクの一覧を記述することができます。 [[cref属性>#xmlelement_crefattribute]]で指定された型・メンバへのリンクが「参照」のセクションに追加されます。
seealso要素を使うことで、親クラスやオーバーロードされた他のメソッド、類似するメンバなどのリンクの一覧を記述することができます。 cref属性の指定方法は[[メンバのID>#xmlelement_memberid]]で解説します。
 
seealso要素は他の要素とは異なり説明文を記述することはできません。 また、seealso要素は説明文中でメンバへのリンクを記述するsee要素とは異なります。
seealso要素は他の要素とは異なり説明文を記述することはできません。 また、seealso要素は説明文中でメンバへのリンクを記述するsee要素とは異なります。
 
}}|
}}|
~
|~リンクを作成するための要素|~see要素|<see cref="&var{member};"/>|[[cref属性>#xmlelement_crefattribute]]で指定されたメンバ&var{member};へのリンクを指定します。 see要素は説明文中で型やメンバのリンクを作成するために使用します(seealso要素とは異なります)。|
|~リンクを作成するための要素|~see要素|<see cref="&var{member};"/>|指定されたメンバ&var{member};へのリンクを指定します。 &var{member};には任意の型やメソッドを指定することが出来ます。 cref属性の指定方法は[[メンバのID>#xmlelement_memberid]]で解説します。|
 
|~|~paramref要素|<paramref name="&var{name};"/>|指定された引数&var{name};の説明へのリンクを指定します。|
|~|~paramref要素|<paramref name="&var{name};"/>|指定された引数&var{name};の説明へのリンクを指定します。|
 
|~|~typeparamref要素|<typeparamref name="&var{name};"/>|指定された型パラメータ&var{name};の説明へのリンクを指定します。|
|~|~typeparamref要素|<typeparamref name="&var{name};"/>|指定された型パラメータ&var{name};の説明へのリンクを指定します。|
 
|~説明文内でのマークアップを行う要素|~para要素|<para>...</para>|説明文の段落を定義します。 これはXHTML/HTMLのp要素やdiv要素に相当する要素です。|
|~説明文内でのマークアップを行う要素|~para要素|<para>...</para>|説明文の段落を定義します。 これはXHTML/HTMLのp要素やdiv要素に相当する要素です。|
253,122 253,14
 
</doc>
</doc>
 
}}
}}
 

        

        
~
**cref属性 [#xmlelement_crefattribute]
**メンバのID [#xmlelement_memberid]
~
exception要素・seealso要素・see要素では、cref属性に記述された型やメンバを参照します。 cref属性に型名・メンバ名を記述する際の要点として、次の事項が挙げられます。
see要素やexception要素ではcref属性で型やメンバのIDを指定することにより、リンクを作成することが出来ます。 このIDは、「&var{メンバの種類};:&var{完全限定名};」の形式で定義されています。 メンバの種類は一文字で表され、型を表す''T''やメソッドを表す''M''などを指定します。 例えば、型であれば「T:&var{名前空間};.&var{型名};」となり、メソッドであれば「M:&var{名前空間};.&var{型名};.&var{メソッド名};(&var{引数リスト};)」のようになります。
 

        

        
~
-cref属性では、コード中から参照する場合と同じように参照する型やメンバのスコープが適用される
IDの規則といくつかの例を表にまとめると次のようになります。
+
--同一クラス内のメンバを参照する場合はクラス名を省略できる
+
--異なるクラスのメンバを参照する場合はクラス名から記述する必要がある
+
--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の規則といくつかの変換例を表にまとめると次のようになります。
 

        

        
 
|*IDの規則
|*IDの規則
 
|>|>|~IDの例|h
|>|>|~IDの例|h
~
|~種類|~変換例|~IDが表すメンバ|h
|~種類|~例|~IDが表すメンバ|h
 
|~N (名前空間)|N:System.Collections|System.Collections名前空間|
|~N (名前空間)|N:System.Collections|System.Collections名前空間|
 
|~T (型)&br;クラス/インターフェイス/構造体/列挙体/デリゲート|T:System.String|Stringクラス|
|~T (型)&br;クラス/インターフェイス/構造体/列挙体/デリゲート|T:System.String|Stringクラス|
 
|~|T:System.ArgumentException|ArgumentException例外クラス|
|~|T:System.ArgumentException|ArgumentException例外クラス|
439,70 331,6
 
M:FooNamespace.BarClass.BazMethod(System.Int32[],System.Int32[][],System.Int32[0:,0:])
M:FooNamespace.BarClass.BazMethod(System.Int32[],System.Int32[][],System.Int32[0:,0:])
 
}}
}}
 

        

        
+

          
+
**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&lt;string&gt;();
+
///
+
///    list.Add("foo");
+
///    list.Add("bar");
+
///
+
///    if (0 &lt; 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&lt;string&gt;();
+
    
+
        list.Add("foo");
+
        list.Add("bar");
+
    
+
        if (0 &lt; list.Count)
+
          list.Add("baz");
+
      </code>
+
     </example>
+
</member>
+
}}
+

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

          
 
**外部ドキュメントのインクルード (include要素) [#include_document]
**外部ドキュメントのインクルード (include要素) [#include_document]
 
XMLドキュメントコメントでは、&msdn(netfx,id,9h8dy30z){include要素};を使うことで外部のXMLファイルからドキュメントをインクルードすることができます。 include要素を使うことでドキュメントをソースコード上ではなく別のファイルで管理したり、ソース上の複数箇所で同じ説明文が記述されることがないよう定型文を外部ファイル化したりすることができます。
XMLドキュメントコメントでは、&msdn(netfx,id,9h8dy30z){include要素};を使うことで外部のXMLファイルからドキュメントをインクルードすることができます。 include要素を使うことでドキュメントをソースコード上ではなく別のファイルで管理したり、ソース上の複数箇所で同じ説明文が記述されることがないよう定型文を外部ファイル化したりすることができます。