Visual Studio .NETによるチーム開発事始め Visual C# .NETでAPIリファレンスを作る（後編） 一色 政彦 2003/07/01
Page1 Page2 Page3 Page4

2．クラス・メンバの詳細情報を記述する

　APIリファレンスで、クラス・メンバ（フィールド、メソッド、プロパティ、インデクサなど）の詳細情報を表示するためには、クラスの場合と同様に「ドキュメント コメントのタグ」を使って、メンバごとにコメントを記述する必要がある。

■フィールドで使えるタグ

　フィールドでは、<summary>タグ、<remarks>タグ、<newpara>タグを使用できる。

　<summary>のコメントではフィールドの意味や内容を書く。<remarks>のコメントではフィールドを使用するときの注意点を記述したり、フィールドをフラグとして利用している場合はそのフラグの値の意味を記述したりするとよいだろう。ドキュメント・コメントのタグ入力とその出力例は次のようになる。

/// <summary> /// 最新の計算結果を演算子タイプごとに保持している。 /// </summary> /// <remarks> /// 配列の0番目は［＋］、1番目は［−］、2番目は［×］、3番目は［÷］の計算結果を保持している。 /// </remarks> private double [] resarray;

入力例：APIリファレンスの生成元となるソース・コード

　

出力例：生成されたAPIリファレンス

<summary>タグで囲んだコメント（フィールドの概要） 　 自動生成されるため、コメントは記述できない 　 自動生成されるため、コメントは記述できない 　 <remarks>タグで囲んだコメント（フィールドの詳しい解説）

■メソッドで使えるタグ

　メソッドでは、<summary>タグ、<remarks>タグ、<newpara>タグ、<param>タグ、<returns>タグを使うことができる。

　<param>のコメントではメソッドの引数の説明を書き、<returns>のコメントではメソッドの戻り値の説明を記述する。<remarks>のコメントでは、メソッドの使用例や使用条件、注意点などを記述するとよいだろう。

　なお、<param>タグは、複数の引数を区別するために、name属性を持っている。すべての<param>タグはname属性で引数の名前を指定する必要がある。次の例では、name属性に「arg1」や「arg2」という引数名を指定している。

/// <summary> /// 足し算を行います。 /// </summary> /// <param name="arg1">左辺の数値</param> /// <param name="arg2">右辺の数値</param> /// <returns>演算結果</returns> /// <remarks> /// メソッドの使用例 /// <newpara> /// Calculator calc = new Calculator(); /// </newpara> /// <newpara> /// double ret = calc.Plus(2, 3); /// </newpara> /// </remarks> public double Plus(double arg1, double arg2) {   …… }

入力例：APIリファレンスの生成元となるソース・コード

　

出力例：生成されたAPIリファレンス

<summary>タグで囲んだコメント（メソッドの概要） 　 コメントは記述できない 　 <param>タグで囲んだコメント（引数の説明） 　 <returns>タグで囲んだコメント（戻り値の説明） 　 <remarks>タグで囲んだコメント（メソッドの詳しい解説）

■プロパティで使えるタグ

　プロパティでは、<summary>タグ、<remarks>タグ、<newpara>タグを使用できる。

　<summary>のコメントでプロパティの説明を書き、<remarks>のコメントでプロパティの設定や取得（アクセサ）について記述するとよいだろう。アクセサ・メソッド自体にAPIリファレンスのためのコメントは記述できないので、注意が必要である（アクセサについては本稿前編の「4．メンバ情報の参照」を参照）。

/// <summary> /// 最新の計算結果を取得できます。 /// </summary> /// <remarks> /// 足し算・引き算・掛け算・割り算、いずれかの計算結果。 /// </remarks> public double result {   get { …… }   set { …… } }

入力例：APIリファレンスの生成元となるソース・コード

　

出力例：生成されたAPIリファレンス

<summary>タグで囲んだコメント（プロパティの概要） 　 コメントは記述できない 　 コメントは記述できない 　 アクセサ・メソッドのコメントは記述できない。<remarks>のコメントでアクセサ・メソッドについて記述するとよいだろう 　 <remarks>タグで囲んだコメント（プロパティの詳しい解説）

■インデクサで使えるタグ

　インデクサでは、<summary>タグ、<remarks>タグ、<newpara>タグを使うことができる。

　<summary>のコメントにはインデクサの説明を書き、<remarks>のコメントにはインデックスの意味とインデクサの使い方を記述するとよい。プロパティと同様に、アクセサ・メソッドのコメントは書くことができない（インデクサについては本稿前編の「 4．メンバ情報の参照」を参照）。

/// <summary> /// インデックスを指定して最新の計算結果を取得します。 /// </summary> /// <remarks> /// [0]･･･足し算の計算結果／ /// [1]･･･引き算の計算結果／ /// [2]･･･掛け算の計算結果／ /// [3]･･･割り算の計算結果／ /// </remarks> public double this[byte index] {   get { …… }   set { …… } }

入力例：APIリファレンスの生成元となるソース・コード

　

出力例：生成されたAPIリファレンス

<summary>タグで囲んだコメント（インデクサの概要） 　 コメントは記述できない 　 コメントは記述できない 　 プロパティの場合と同様に、アクセサ・メソッドのコメントは記述できない 　 <remarks>タグで囲んだコメント（インデクサの詳しい解説）

　続いて、これらのタグの入力について解説しよう。

INDEX
	Visual Studio .NETによるチーム開発事始め
	Visual C# .NETでAPIリファレンスを作る（後編）
	1．「ドキュメント コメントのタグ」の概要
	2．クラス・メンバの詳細情報を記述する
	3．ドキュメント・コメントの入力テクニック
	4．APIリファレンスの応用・関連知識

　

「Visual Studio .NETによるチーム開発事始め」

＠ITメールマガジン　新着情報やスタッフのコラムがメールで届きます（無料）