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を使ったチーム開発をより快適にすることを目指した連載である。チーム開発の現場で役に立つ機能やツール、使い方を紹介していくので、次回もご期待いただきたい。End of Article


 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 記事ランキング

本日 月間