Visual Studio .NETによるチーム開発事始め Visual C# .NETでAPIリファレンスを作る(後編)一色 政彦2003/07/01 |
|
|
2.クラス・メンバの詳細情報を記述する
APIリファレンスで、クラス・メンバ(フィールド、メソッド、プロパティ、インデクサなど)の詳細情報を表示するためには、クラスの場合と同様に「ドキュメント コメントのタグ」を使って、メンバごとにコメントを記述する必要がある。
■フィールドで使えるタグ
フィールドでは、<summary>タグ、<remarks>タグ、<newpara>タグを使用できる。
<summary>のコメントではフィールドの意味や内容を書く。<remarks>のコメントではフィールドを使用するときの注意点を記述したり、フィールドをフラグとして利用している場合はそのフラグの値の意味を記述したりするとよいだろう。ドキュメント・コメントのタグ入力とその出力例は次のようになる。
|
|
入力例:APIリファレンスの生成元となるソース・コード |
出力例:生成されたAPIリファレンス | ||||||||||||
|
■メソッドで使えるタグ
メソッドでは、<summary>タグ、<remarks>タグ、<newpara>タグ、<param>タグ、<returns>タグを使うことができる。
<param>のコメントではメソッドの引数の説明を書き、<returns>のコメントではメソッドの戻り値の説明を記述する。<remarks>のコメントでは、メソッドの使用例や使用条件、注意点などを記述するとよいだろう。
なお、<param>タグは、複数の引数を区別するために、name属性を持っている。すべての<param>タグはname属性で引数の名前を指定する必要がある。次の例では、name属性に「arg1」や「arg2」という引数名を指定している。
|
|
入力例:APIリファレンスの生成元となるソース・コード |
出力例:生成されたAPIリファレンス | |||||||||||||||
|
■プロパティで使えるタグ
プロパティでは、<summary>タグ、<remarks>タグ、<newpara>タグを使用できる。
<summary>のコメントでプロパティの説明を書き、<remarks>のコメントでプロパティの設定や取得(アクセサ)について記述するとよいだろう。アクセサ・メソッド自体にAPIリファレンスのためのコメントは記述できないので、注意が必要である(アクセサについては本稿前編の「4.メンバ情報の参照」を参照)。
|
|
入力例:APIリファレンスの生成元となるソース・コード |
出力例:生成されたAPIリファレンス | |||||||||||||||
|
■インデクサで使えるタグ
インデクサでは、<summary>タグ、<remarks>タグ、<newpara>タグを使うことができる。
<summary>のコメントにはインデクサの説明を書き、<remarks>のコメントにはインデックスの意味とインデクサの使い方を記述するとよい。プロパティと同様に、アクセサ・メソッドのコメントは書くことができない(インデクサについては本稿前編の「 4.メンバ情報の参照」を参照)。
|
|
入力例:APIリファレンスの生成元となるソース・コード |
出力例:生成されたAPIリファレンス | |||||||||||||||
|
続いて、これらのタグの入力について解説しよう。
INDEX | ||
Visual Studio .NETによるチーム開発事始め | ||
Visual C# .NETでAPIリファレンスを作る(後編) | ||
1.「ドキュメント コメントのタグ」の概要 | ||
2.クラス・メンバの詳細情報を記述する | ||
3.ドキュメント・コメントの入力テクニック | ||
4.APIリファレンスの応用・関連知識 | ||
「Visual Studio .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用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
|
|