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

Page1 Page2 Page3 Page4

Back Issue

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

　前回はVisual Studio .NET（以下、VS.NET）でのAPIリファレンスの作成方法とその内容について解説した。今回は、APIリファレンスを生成する仕組みである「ドキュメント コメントのタグ」の書き方や、APIリファレンスの応用・関連知識について解説しよう。

1．「ドキュメント コメントのタグ」の概要

　Visual Studio .NETでは、プログラムのソース・コードからAPIリファレンスを自動生成することができる。APIリファレンスを生成するために、VS.NETは、ソース・コード内に記述されたXMLタグを元にAPIリファレンス用のコメントを抽出する。このようなXMLタグは「ドキュメント コメントのタグ」と呼ばれている。

■APIリファレンスとXMLドキュメント・コメント

　Visual C# .NETには、「ドキュメント コメントのタグ」を使った機能が2つある。1つ目が本稿の主題であるAPIリファレンス（VS.NETでは「コード・コメントWebレポート」と呼ばれる）、2つ目がXMLドキュメント・コメントである。

　APIリファレンスとXMLドキュメント・コメントとの違いは、APIリファレンスがHTML出力に対応しているのに対し、XMLドキュメント・コメントはXML出力に対応していることである。APIリファレンスは手軽にブラウザで表示できるが、インターフェイスをカスタマイズできない。XMLドキュメント・コメントは、そのままではブラウザに表示できないが、XMLであるがゆえに独自の自由なインターフェイスを作り込むことができる。

　また、APIリファレンスは一部のドキュメント・コメントのタグにのみ対応しており、タグの種類が少なく簡単に覚えられるのですぐに利用できるが、その反面表現力に乏しい。一方、XMLドキュメント・コメントはすべてのドキュメント・コメントのタグに対応しているので、多くのタグを覚えて使い分けるのに手間はかかるが豊かな表現が可能である。

　よって、コストをかけずにすぐに使いたいならAPIリファレンスを、独自のインターフェイスで表現力豊かなリファレンス・マニュアルを構築するのならXMLドキュメント・コメントを利用するのがよいだろう。

　本稿の主題はAPIリファレンスである。XMLドキュメント・コメントについては「4. APIリファレンスの応用・関連知識」で軽く触れることにする。

■ドキュメント・コメントのタグ

　APIリファレンスで利用する「ドキュメント・コメントのタグ」は、次の表に示す5つしかない。

タグ	説明
<summary>〜</summary>	「概要」を記述する
<remarks>〜</remarks>	「解説」を記述する
<param>〜</param>	メソッドの「引数」の説明を記述する
<returns>〜</returns>	メソッドの「戻り値」の説明を記述する
<newpara>〜</newpara>	書式設定。「概要」、「解説」、「戻り値」の記述の中に「段落」を作る
APIリファレンスで利用する「ドキュメント・コメントのタグ」
タグの「〜」の部分にコメントを入力する。

　ドキュメント・コメントは、クラスとクラスのメンバ（フィールド、メソッド、プロパティ、インデクサなど）で利用できる。ただし、<param>タグと<returns>タグが使用できるのは、メソッドの場合のみである。

■クラスで使えるタグ

　クラスでは、<summary>タグ、<remarks>タグ、<newpara>タグを使うことができる。

　<summary>〜</summary>で囲んだ部分は「クラス概要」のコメントになり、<remarks>〜</remarks>で囲んだ部分は「クラスの詳しい解説」のコメントになる。<summary>タグや<remarks>タグのコメント中に<newpara>〜</newpara>を挿入すると、その部分が段落になる。

　それでは、クラスでのドキュメント・コメントのタグの入力例とAPIリファレンスの出力例を見てみよう。

/// <summary> /// Calculatorクラスの概要･･･▼ /// <newpara> /// 四則演算を行うためのクラスです。 /// </newpara> /// </summary> /// <remarks> /// Calculatorクラスの解説･･･▼ /// <newpara> /// 四則演算の足し算［＋］、引き算［−］、掛け算［×］、割り算［÷］を行うメソッドがあります。 /// </newpara> /// </remarks> public class Calculator {   …… }

入力例：APIリファレンスの生成元となるソース・コード

<summary>タグで「クラスの概要」のコメントを記述、<remarks>タグで「クラスの詳しい解説」のコメントを記述している。それぞれのコメントの中で<newpara>タグを使い、「段落」を作っている。

　上記のソース・コードを見ていただいても分かるように、ドキュメント・コメントのためのタグは、C#の単一行コメントである「//」にさらにスラッシュを加えた特別なコメントとして記述する。

　このソース・コードからAPIリファレンスを生成すると次のようになる。

出力例：VS.NETで生成したAPIリファレンス

<summary>タグで囲んだコメント（クラスの概要） 　 「クラスの概要」のコメントの中で、<newpara>タグで区切った部分が段落になっている 　 自動生成されるため、コメントは記述できない 　 自動生成されるため、コメントは記述できない 　 クラス・メンバごとの<summary>タグで囲んだコメント。クラス・メンバの概要の書き方は後述する 　 <remarks>タグで囲んだコメント（クラスの詳しい解説） 　 「クラスの詳しい解説」の中で、<newpara>タグで区切った部分が段落になっている

　続いて、クラス内の各メンバでのタグについて解説していこう。

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

　

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

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