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

2. APIリファレンスの作成方法

　ここでは、単純な四則演算を行うプログラム「MyCalc」（下の画面参照）と、その演算処理を担うクラス・ライブラリ「CalcLib」を使って、APIリファレンスの生成方法を具体的に説明しよう。なお、クラス・ライブラリ「CalcLib」はチーム内で共有されているという前提である。本稿では、この「CalcLib」を中心に解説を進めていく。

四則演算を行うサンプル・アプリケーション「MyCalc」

「MyCalc」は、クラス・ライブラリ「CalcLib」の演算処理機能を使用している。演算する数値と演算子を選択すると、演算結果が表示される簡単なサンプルである。

サンプル・アプリケーションのVisual C#プロジェクトのダウンロードはこちら

　実際の作成手順に入る前に、このサンプル・アプリケーションにAPIリファレンスがある場合とない場合の比較を示しておこう。クラス・ライブラリ「CalcLib」に含まれるFractionsクラス（端数処理機能を実装したクラス）のクラス・メンバ「Round()メソッド」（四捨五入を行うメソッド）を例に挙げて説明する。このメソッドには、小数第1位ではなく、小数第2位で四捨五入するという注意すべき仕様がある。

/// <summary> /// 小数第2位を四捨五入します。 /// </summary> /// <param name="arg1">元の値</param> /// <returns>端数処理後の値</returns> public double Round(double arg1) {   decimal dectmp = Convert.ToDecimal(arg1);   dectmp *= 10;   dectmp += 0.5m;   dectmp = Decimal.Truncate(dectmp);   dectmp /= 10;   double dret = Convert.ToDouble(dectmp);   return dret; }

FractionsクラスのRound()メソッドのソース・コード

　

FractionsクラスのRound()メソッドのAPIリファレンス

　

	APIリファレンス“なし”	APIリファレンス“あり”
時間と労力のコスト（生産性）	クラス・ライブラリのソース・コードを追って、メソッド仕様を調べる必要がある 例：Round()メソッドの仕様をソース・コードから確認した	APIリファレンスに記述された仕様をより簡単に参照できる 例：Round()メソッドの仕様をAPIリファレンスで確認した→生産性の向上！
トラブル発生の可能性（リスク）	クラス・ライブラリが膨大であればあるほど、すべてのメソッドについてソース・コードの中を参照して、メソッドの仕様を確認するのは大変な作業になる。その結果、調べ方が甘くなり、見落としや勘違いの可能性が増大する 例：Round()メソッドの仕様をよく確認せずに、小数第1位で四捨五入すると勘違いした→バグになってしまう！	情報が見やすくまとめられているので、メソッド仕様の参照と理解が容易になり、見落としや勘違いの可能性をより低減できる 例：Round()メソッドの解説が見やすくまとめられているので、仕様を正確に把握できた→トラブルのリスクを低減できる！

　もちろんAPIリファレンスがあるとしても「時間と労力のコスト」や「トラブル発生の可能性」はあるのだが、APIリファレンスがある方がより開発の生産性を向上させることができ、リスクも低減させることができると考えられる。

■APIリファレンスの生成手順

　それでは、とりあえずは現状のままで、VS.NETの機能を利用して、ソース・コードからMyCalcのAPIリファレンスを生成してみよう。これにはまず、VS.NETでC#のソリューション（プロジェクト）を開き、統合開発環境のメニューから、［ツール］−［Webページのビルド コメント］を実行する。するとAPIリファレンスを生成するためのダイアログ・ボックスが表示される。

　メニュー名から分かるとおり、VS.NETでは、APIリファレンスのことを「Webページのビルド コメント」や「コード コメントWebレポート」と呼んでいる。ただし本稿では、以後も、より一般性が高いと思われる「APIリファレンス」という表記を使う。

［Web ページのビルド コメント］ダイアログ・ボックス

統合開発環境のメニューから、［ツール］−［Webページのビルド コメント］を実行すると、このダイアログが開く。ここでは、APIリファレンスを生成する範囲（ソリューション全体か、指定プロジェクトのみか）とAPIリファレンスを生成する場所を指定する。

ソリューション全体のAPIリファレンスを生成する 　 下のプロジェクト一覧からプロジェクトを選択し、選択したプロジェクトに関するAPIリファレンスだけを生成する 　 APIリファレンスの保存先を指定する 　 APIリファレンスへのショートカットをブラウザのブックマークに追加する場合はこれをオンにする

　今回は［ソリューション全体］を選択し、APIリファレンスの生成場所として「C:\ApiDoc\MyCalc」を指定してみる。最後に［OK］ボタンをクリックすると、APIリファレンスが生成される。以上でAPIリファレンスの作成は完了である。

INDEX
	Visual Studio .NETによるチーム開発事始め
	Visual C# .NETでAPIリファレンスを作る（前編）
	1．APIリファレンスのすすめ
	2．APIリファレンスの作成方法
	3．APIリファレンスを表示する
	4．APIリファレンスの概要
	5．クラス・メンバの詳細情報を参照する

　

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

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