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によるチーム開発事始め」


Insider.NET フォーラム 新着記事
  • 第2回 簡潔なコーディングのために (2017/7/26)
     ラムダ式で記述できるメンバの増加、throw式、out変数、タプルなど、C# 7には以前よりもコードを簡潔に記述できるような機能が導入されている
  • 第1回 Visual Studio Codeデバッグの基礎知識 (2017/7/21)
     Node.jsプログラムをデバッグしながら、Visual Studio Codeに統合されているデバッグ機能の基本の「キ」をマスターしよう
  • 第1回 明瞭なコーディングのために (2017/7/19)
     C# 7で追加された新機能の中から、「数値リテラル構文の改善」と「ローカル関数」を紹介する。これらは分かりやすいコードを記述するのに使える
  • Presentation Translator (2017/7/18)
     Presentation TranslatorはPowerPoint用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)

注目のテーマ

Insider.NET 記事ランキング

本日 月間