特集：ツールを使ったドキュメント作成技法（前編） 価値のある開発ドキュメントを効率的に作成するには？ アバナード株式会社　市川 龍太（Microsoft MVP 2008 for XML） 2008/05/20
Page1 Page2 Page3

●XMLドキュメント・コメントを記述したソース・コードの作成

　まずはVisual Studio 2008やVisual Studio 2005でコンソール・アプリケーションを新規作成し（プロジェクトの名前は「SandCastleSample」とする）、サンプル・プログラムとして以下のコードを記述する。

using System; namespace SandCastleSample {   /// <summary>   /// エントリ・ポイント・クラス   /// </summary>   class Program   {     /// <summary>     /// メイン・エントリ・ポイント     /// </summary>     /// <param name="args">コマンドライン引数配列</param>     static void Main(string[] args)     {       SampleClass sample = new SampleClass();       sample.ShowMessage(         "サンプル太郎", "ドキュメントは大事ですよ。");     }   }   /// <summary>   /// サンプルクラス   /// </summary>   public class SampleClass   {     /// <summary>     /// メッセージを表示する     /// </summary>     /// <param name="name">メッセージの対象者</param>     /// <param name="message">メッセージの本文</param>     public void ShowMessage(string name, string message)     {       Console.WriteLine(         string.Format("{0}さんへメッセージです。", name));       Console.WriteLine(string.Format("{0}", message));       Console.ReadLine();     }   } } ''' <summary> ''' エントリ・ポイント・モジュール ''' </summary> Module Program   ''' <summary>   ''' メイン・エントリ・ポイント   ''' </summary>   ''' <param name="args">コマンドライン引数配列</param>   Sub Main(ByVal args() As String)     Dim sample As New SampleClass()     sample.ShowMessage( _       "サンプル太郎", "ドキュメントは大事ですよ。")   End Sub End Module ''' <summary> ''' サンプルクラス ''' </summary> Public Class SampleClass   ''' <summary>   ''' メッセージを表示する   ''' </summary>   ''' <param name="name">メッセージの対象者</param>   ''' <param name="message">メッセージの本文</param>   Public Sub ShowMessage(ByVal name As String, ByVal message As String)     Console.WriteLine( _       String.Format("{0}さんへメッセージです。", name))     Console.WriteLine(String.Format("{0}", message))     Console.ReadLine()   End Sub End Class

コンソール画面にメッセージを表示するサンプル・プログラム（上：C#、下：VB）

　このコードでは「<summary>」などのタグを使ってXMLドキュメント・コメントが記述されている。Visual Studioのコード・エディタでは、C#では「///」、VBでは「'''」のようにコメント記号を3つ続けて記述することで、「<summary>」などのXMLドキュメント・コメントを自動挿入できる。XMLドキュメント・コメントのタグは、IntelliSenseからも入力できる。なお、VBではXMLドキュメント・コメントに対応しているバージョンは、Visual Studio 2005以降なので注意してほしい。

●XMLドキュメント・コメントのタグ一覧

　参考までに、XMLドキュメント・コメントの主要なタグについて簡単にまとめた。

タグ	説明
<summary>	「概要」を記述する 用法：<summary>概要</summary>
<remarks>	「解説」を記述する 用法：<remarks>解説</remarks>
<param>	name属性にメソッドの「（1つの）パラメータの名前」を指定して、そのパラメータの「説明」を記述する 用法：<param name="パラメータの名前">説明</param>
<typeparam>	name属性にジェネリック型やジェネリック・メソッドの「型パラメータの名前」を指定して、その型パラメータの「説明」を記述する 用法：<typeparam name="型パラメータの名前">説明</typeparam>
<returns>	メソッドの「戻り値の説明」を記述する 用法：<returns>戻り値の説明</returns>
<value>	「プロパティの説明」を記述する 用法：<value>プロパティの説明</value>
<example>	「サンプル・コード」を記述する 用法：<example>サンプル・コード</example>
<exception>	cref属性に「例外クラスの名前」を指定して、その例外の「説明」を記述する。例外クラスの名前は、例えば「System.OverflowException」などのように名前空間を付けた名前 用法：<exception cref="例外クラスの名前">説明</exception>
XMLドキュメント・コメントのタグ一覧
ちなみにXMLドキュメント・コメントのテキスト内に「<」や「>」を記述したいときは、HTMLコードと同じように「&lt;」や「&gt;」を使用する。

　このほか、<summary>タグ、<remarks>タグ、<returns>タグなどで囲んだテキストの中で使用できる「書式指定タグ」も用意されている。これについても次の表に簡単にまとめたが、用法についてはMSDN（C#、VB）を参照してほしい。

書式指定タグ	説明
<para>	「段落」を作る
<list>	個条書きや番号付きの「リスト」を作る
<paramref>	「パラメータへの参照」を作る
<typeparamref>	「型パラメータへの参照」を作る
<c>	一部分のテキストを「コード表記」にする
<seealso>	「クラスやメンバへの参照」（セクション）を作成する
<see>	クラスやメンバへの「テキスト・リンク」を作成する
XMLドキュメント・コメントの「書式指定タグ」一覧
これらのタグは<summary>タグ、<remarks>タグ、<returns>タグで囲んだテキストの中で使用できる。 このほかに、<example>タグで囲んだテキストの中で使用できる「<code>タグ」がある。これは<c>タグと同じように、一部分のテキストを「コード表記」にする。

●XMLドキュメント・ファイルの生成

　続いて［ソリューション エクスプローラ］のプロジェクト項目（ここでは「SandCastleSample」）を右クリックして、表示されるコンテキスト・メニューから［プロパティ］を選択し、プロジェクト・プロパティの設定画面を表示する。

　C#では［ビルド］タブを開き、［XML ドキュメント ファイル］チェックボックスにチェックを入れる（VBでは［コンパイル］タブを開き、［XML ドキュメント ファイルを生成する］チェックボックスにチェックを入れる）。

SandCastleSampleプロジェクトのプロパティ設定画面（C#）

XMLドキュメント・ファイルを生成するオプションを設定する。

XMLドキュメント・ファイルに出力先パスを指定する。

　最後にプロジェクトをビルドすれば、サンプル・アプリケーションの実行形式ファイル（SandCastleSample.exe）と同じフォルダにSandCastleSample.XMLファイルが生成されているはずである。

　以上でソース・コード側の準備は完了したので、あとは実際にSandcastleを使用してCHM形式ファイルを生成していこう。この際に、Sandcastle Help File Builderを使用すると作業が楽になる。

●Sandcastle Help File Builderの使い方

　Sandcastle Help File Builderを使用するには、［スタート］メニューから［すべてのプログラム］−［Sandcastle Help File Builder］−［Sandcastle Help File Builder GUI］を選択し、Sandcastle Help File Builderを起動する。

Sandcastle Help File Builderの画面

まず［Project Properties］の各パラメータを設定する。この例では［Language］プロパティに「日本語（日本）」を設定している。

　［Project Properties］の各パラメータを設定することで、例えば継承元のクラスのメンバについては出力対象外にしたり、パブリックなメンバのみを出力対象にしたりといった細かい設定ができるようになっている。パラメータの設定が終わったら［Add］ボタンを押し、サンプル・アプリケーションの実行形式ファイル（ここでは先ほど生成した「SandCastleSample.exe」）を指定する。最後に、メニュー・バーから［Documentation］−［Build Project］を選択すれば、CHM形式ファイルが生成され、作業は完了である。

　生成されたCHM形式ファイルを確認したい場合は、メニュー・バーから［Documentation］−［View Help File］−［View Help File］を選択すれば、簡単に確認できる。以下にサンプル・プログラムから自動生成されたCHM形式ファイルの例を示す。

自動生成されたCHM形式ファイル

CHM形式ファイルを確認するには、メニュー・バーから［Documentation］−［View Help File］−［View Help File］を選択すればよい。

言語タブを切り替えることで各言語に応じたシンタックス定義に切り替えることができる。

　このようにソース・コード上に決められた書式でXMLドキュメント・コメントを記述しておけば、Sandcastleを使用してCHM形式のドキュメントを簡単に自動生成できるのである。前述した「開発時に作成されるドキュメント一覧」の中にクラス設計書があるが、実際の業務システムではクラスの数が3けたに及ぶこともある。これらクラスの定義をいちいち書いていては非常に工数がかかってしまう。そういった場合にSandcastleを使用すれば、その工数を随分と削減できるだろう。

■

　今回は、価値のあるドキュメントを書くためのコツと、効率的にドキュメントを作成するツールとしてSandcastleを紹介した。後編では、Sandcastleと、もう1つの別のツールであるGhostDocを組み合わせたドキュメント作成技法や、patterns & practices Documentation Toolsについて紹介する予定である。

INDEX
	[特集]
	ツールを使ったドキュメント作成技法（前編）
	価値のある開発ドキュメントを効率的に作成するには？
	1. アジャイル・ドキュメントとは何か？
	2. 価値のあるドキュメントを作成するコツ
	3. ツールを使ったドキュメントの作成技法
	ツールを使ったドキュメント作成技法（後編）
	マイクロソフトも実施しているドキュメント作成技法
	1. 柔軟なXMLドキュメント・コメントを生成する「GhostDoc」
	2. GhostDocとSandCastleを組み合わせたドキュメント作成技法
	3. マイクロソフトも活用する「patterns & practices Documentation Tools」

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