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

4．APIリファレンスの応用・関連知識

■APIリファレンスの共有

　APIリファレンスは開発者にとって欠かせない、便利なツールである。このツールをチームのメンバーがそれぞれ個別に所有するのではなく、チームで共有することができればもっと便利になるだろう。APIリファレンスを共有する方法としては、APIリファレンスをWebサイトにして、チーム内に公開するのがお勧めだ。Webサイトを立ち上げるには、WindowsのIISなどのHTTPサーバを利用するとよいだろう。IISの使用方法については、本稿の本旨から外れるのでここでは省略する。

■XMLドキュメント・コメント

　1. 「ドキュメント・コメントのタグ」の概要でも説明したように、VS.NETでC#を使う場合、APIリファレンスだけでなく、XMLドキュメント・コメントも出力することができる。独自のAPIリファレンスを構築したい場合には、XMLドキュメント・コメントの方がお勧めだ。独自にXSLTスタイルシートを作成すれば、Webページ化することができる。また、XMLドキュメント・コメントはXMLデータなので、独自の検索機能を追加するなどのカスタマイズが自由に行える。

XMLドキュメント・コメントとXSLTスタイルシートによるWebページの例

サンプルはこちらからダウンロードできる。

　それでは、XMLドキュメント・コメントの出力手順について見ていこう。

　Visual Studio .NETで、C#プロジェクトのソリューションを開き、ソリューション・エクスプローラで、プロジェクトを右クリックしてメニューから［プロパティ］を選択する（または、ソリューション・エクスプローラで、プロジェクトを選択し、統合開発環境の［表示］メニューから［プロパティページ］を選ぶ）。

統合開発環境（Visual Studio .NET）

「ソリューション エクスプローラ」 　 ［プロジェクト］を右クリックして、メニューから［プロパティ］を選ぶ

　すると、C#プロジェクトの「プロパティ ページ」が表示される。

「プロパティ ページ」でのXMLドキュメント・コメントの出力設定

ビルド時にXMLドキュメント・コメントのファイルを出力するかしないかを設定できる。

［構成プロパティ］フォルダをクリックして開く 　 ［ビルド］をクリック 　 ビルドの［出力］設定 　 ［XML ドキュメント ファイル］にファイル名を入力すると、XMLドキュメント・コメントのファイル（.xmlファイル）が出力されるようになる

　プロジェクトまたはソリューションのビルドを実行すると、XMLドキュメント・コメントのファイルが指定したパスに出力される。

　XMLドキュメント・コメントのファイルの出力は次のようになる。

XMLドキュメント・コメントの出力例

コメントが構造化されたXMLファイルが出力される。

　参考として、XMLドキュメント・コメントの出力で使用できる「ドキュメント コメントのタグ」を表にまとめておいた。

タグ	説明
<summary>	「概要」を記述する
< remarks >	「解説」を記述する
<param>	メソッドの「引数」の説明を記述する
<returns>	メソッドの「戻り値」の説明を記述する
<value>	「プロパティ」の説明を記述する
<exception>	「例外」の説明を記述する
<example>	「サンプル・コード」を記述する
<para>	書式設定。「概要」、「解説」、「戻り値」の記述の中に、「段落」を作る
<list>	書式設定。「概要」、「解説」、「戻り値」の記述の中に、箇条書きや番号付きの「リスト」を作る。各リスト項目には<ITEM>を使う
<parameref>	書式設定。「概要」、「解説」、「戻り値」の記述の中で、一部分を「引数表記」にする
<c>	書式設定。「概要」、「解説」、「戻り値」の記述の中で、一部分を「コード表記」にする
<code>	書式設定。「サンプル・コード」の記述の中で、複数行を「コード表記」にする
<see>	クラスやメンバへの「リンク」を記述する
<seealso>	クラスやメンバへの「参照」を記述する
<permission>	クラスやメンバへの「アクセス許可」を記述する
<include>	外部ファイルに書かれたドキュメント・コメントを引用する
XMLドキュメント・コメントで利用する「ドキュメント・コメントのタグ」
※タグの構文は省略して、タグ名だけを記述しています。

　APIリファレンスで使用できる「段落」作成のタグは<newpara>タグだが、XMLドキュメント・コメントでは<para>タグになるので、注意してほしい。

　APIリファレンスでは、XMLドキュメント・コメントで利用するタグのほとんどが認識されない。特に、<summary>や<remarks>コメント内にタグを記述するときには注意が必要だ。例えば、<remarks>コメント内に<para>タグを記述した場合、VS.NET 2002のAPIリファレンスでは何も表示されないし、VS.NET 2003では<para>タグがそのまま表示されてしまう。VS.NET 2003では、<summary>、<remarks>コメントにHTMLタグを記述した場合も同様にタグがそのまま表示される。

5．まとめ

　今回は、APIリファレンスで開発環境を向上させることを目標に、APIリファレンスの作成方法やコメント内容、タグの入力などについて解説した。

　本連載は、VS.NETを使ったチーム開発をより快適にすることを目指した連載である。チーム開発の現場で役に立つ機能やツール、使い方を紹介していくので、次回もご期待いただきたい。

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

　

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

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