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

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

一色 政彦
2003/06/07

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によるチーム開発事始め」


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

本日 月間