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

Visual C# .NETでAPIリファレンスを作る(後編)

一色 政彦
2003/07/01
Page1 Page2 Page3 Page4

3.ドキュメント・コメントの入力テクニック

 ドキュメント・コメントのタグをVS.NETのエディタで入力するのは簡単である。なぜならば、ドキュメント・コメントのタグは、エディタの入力支援機能を使って、自動入力できるからだ。ここでは、2つの便利な入力支援機能について解説しよう。これらの機能を利用すると、スピーディにドキュメント・コメントを書き加えることができる。

■タグの入力支援機能

 まずは1つ目の入力支援機能を紹介する。コメントを入力したいクラス、メソッド、プロパティの前行で「///」を入力すると、自動的にドキュメント・コメントのタグが入力される。ただし、前行は必ず空行にしておかないと自動入力されないので、注意が必要である。次の例を見てほしい。

タグ入力支援機能(1)「///」
  タグの自動補完前の状態
  「///」を入力中……
  タグの自動補完が完了した状態

 続いて2つ目の入力支援機能を紹介しよう。ドキュメント・コメント・タグの文字を途中まで入力して、[Ctrl]キーを押しながら、[Space]キーを押す(または、統合開発環境のメニューで[編集]−[IntelliSense]−[入力候補]を選択する)と、ドキュメント・コメント・タグの文字を補完できる。または、入力候補から選択できる。タグの最初の文字の「<」を入力すると、入力候補が自動的に表示される。以下の画面を見て、イメージをつかんでほしい。

タグ入力支援機能(2)「入力補完」
ショートカット・キーの設定を変更している場合は、このとおりに動作しない可能性がある
  ドキュメント・コメントのタグを入力中……
  [Ctrl]キーと[Space]キーを同時に押すと、タグが自動的に補完される。また、補完されるタグの入力候補が複数ある場合は、次の「入力候補選択」が表示される
 
タグ入力支援機能(2)「入力候補選択」
ショートカット・キーの設定を変更している場合は、このとおりに動作しない可能性がある
  「<」を入力すると、自動的に「入力候補選択」が表示される。「入力候補選択」が閉じられたあとも、[Ctrl]キーと[Space]キーを同時に押すと、再度「入力候補選択」を表示できる

■Visual Studio .NET 2003の新機能

 Visual Studio .NET 2003では、「/// 〜」形式のコメントだけでなく、「/** 〜 */」形式のコメントも、ドキュメント・コメントとして認識されるようになった。この形式は、Javaのドキュメンテーション・コメントの記述形式とよく似ているが、Javaのドキュメンテーション・コメントのタグの形式は利用できない。利用できるのは、VS.NETで規定されたドキュメント・コメントのタグだけである。また、「/** 〜 */」形式のコメントを使用する場合、「/// 〜」形式のコメントでは使えるタグの入力支援機能が使えないので注意が必要である。

/**
* <summary>
* 足し算を行います。
* </summary>
* <param name="arg1">左辺の数値</param>
* <param name="arg2">右辺の数値</param>
* <returns>演算結果</returns>
*/
public double Plus(double arg1, double arg2) {
  ……
}
「/** 〜 */」形式のドキュメント・コメントの例
VS.NETのドキュメント・コメントのタグの形式を使用して、ドキュメント・コメントを記述する。

 ここまでの内容で、基本的なAPIリファレンスの作成が可能である。ここからは、APIリファレンスの応用や冒頭で紹介した「XMLドキュメント・コメント」など応用的な内容について解説する。


 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メールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)
- PR -

注目のテーマ

Insider.NET 記事ランキング

本日 月間
ソリューションFLASH