Microsoft Visual Studio 2008で開発したAPI等のドキュメントを作成する

VSで作成したAPIにドキュメントをつける為に、Sandcastleを利用してヘルプファイル(XXX.chm)を作成した。
その手順を残しておく。

●全体のながれ
まずはざっくりと簡単なながれから。

1：プログラムにヘルプファイル作成用のコメントを記述する
2：VSのプロジェクトのプロパティにヘルプファイル作成用のXMLを出力する設定をする
3：プロジェクトをビルドする
4：ヘルプファイル作成用のアプリケーションを3種類インストールする
5：ヘルプファイル作成用のアプリケーションの設定をする
6：ヘルプファイル作成用のアプリケーションを実行する
7：ヘルプファイルが完成

●今回ヘルプファイルを作成した環境
OSとかVSのバージョンも残しておく。

・Microsoft Windows XP SP3
・Microsoft Visual Studio 2008
 C#を利用

●コメントの書き方
クラスやメソッドの定義の上に以下のコメントを記述する


/// <summary>
/// 概要を記述
/// </summary>
/// <param name=”arg1″>
/// 引数の説明を記述
/// </param>
/// <returns>
/// 戻り値の説明を記述
/// </returns>
/// <remarks>
/// 解説を記述
/// </remarks>
 

※書き方などは、MSDNや、MS製品のヘルプファイルを参考にすると良いかも。
●ヘルプファイル作成用のXML出力
上記で書いたコメントをプロジェクトのビルド時にXMLファイルとして出力します
設定は、プロジェクトのプロパティにXMLファイルを出力する設定をして、ビルドする
設定方法
1：ソリューションエクスプローラのプロジェクトの上で右クリして、プロパティを選択
※メニューバーのプロジェクト(P)/プロジェクト名のプロパティでも可能
2：ビルドタブの出力項目で「XML ドキュメントファイル(X):」のチェックボックスをクリックして、出力するファイル名を指定する

vspropaty.png
3：ビルドメニューから、ビルドを実行
※ 2で指定したパスにXMLファイルが出力 ★

●ヘルプファイル作成アプリケーションのインストール
上記でいったんVSの作業は終わり。続いて、ヘルプファイルを作成する為に必要なアプリケーションをインストールする
フリーでMicrosoftが提供している以下のアプリケーションを利用した
・Sandcastle
・Sandcastle Help File Builder
・HTML Help 1.4 SDK(Sandcastle Help File Builderでヘルプファイルを作成する時に必要なhhc.exeを提供)

各アプリケーションのインストールしたバージョンとDL先
○Sandcastle – Version 2.4.10520
http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

○Sandcastle Help File Builder 1.8.0.2 Beta
http://www.codeplex.com/SHFB

○HTML Help 1.4 SDK ★★
http://msdn.microsoft.com/en-us/library/ms669985.aspx
Htmlhelp.exe

●ヘルプファイル作成アプリケーションの使用方法
Sandcastle Help File Builderを利用して、ヘルプファイルを作成する

手順
1：スタートメニューより「Sandcastle Help File Builder／Sandcastle Help File Builder GUI」を選択
以下Sandcastle Help File Builderでの手順
2：ヘルプファイルを作成する為にアプリケーションのプロジェクトを作成★★★
 「File」/「New Project」
 ※作成完了後、ヘルプファイルなどを更新する場合、ここで作成したプロジェクトファイルを再度読み込んで利用できる

3：画面右のProject ExplorerのDocumentation Sources上で右クリ「Add Documentation Sources」を選択

helpbuilder.png
4：ファイルを選択画面で、上記の★で作成したXMLファイルを指定
5：プロジェクトのプロパティを設定する
 ヘルプファイルの出力先や、名称などを設定する事が可能
 作成時に最低限必要な設定
 ・「Paths」/「HtmlHelp1xCompilerPath」に★★でインストールしたhhc.exeのあるディレクトリを指定
 ・「Paths」/「WorkingPath」は★★★で作業したプロジェクトを作る先によって、指定しなければいけない場合がある
  ビルド中にエラーが発生する
6：ビルドボタンをクリック
7：Build Outputに以下のメッセージが出力されれば完成
 Build completed successfully at 日付. Total time: 00:02:59.7500
 ※作成するのに3分ほどかかる
8：ヘルプファイル完成
 「Paths」/「OutputPath」でディレクトリを設定した場合は、その場所に
 設定していない場合は、★★★で指定した場所に「Help」のディレクトリが作成され、その中に「Documentation.chm」がある

以上、長い道のりでした。
でも、これでAPIのインターフェース部分のドキュメントが.chmで作成できるなら、いいですね。