DOBON.NET プログラミング道: .NET Framework, VB.NET, C#, Visual Basic, Visual Studio, インストーラ, ...

• クラスライブラリのヘルプ（ドキュメント）を作成する
  • 「コードコメントWebレポート」を作成する
  • NDocを使用してヘルプを作成する
  • Sandcastleを使用してヘルプを作成する
    • SandcastleをGUIから使用するツール
  • その他のツール
• この記事への評価、コメント、トラックバック

クラスライブラリのヘルプ（ドキュメント）を作成する

ここでは、自作したクラスライブラリで定義されているクラスやメンバなどの情報をHTMLやヘルプファイルとして出力する方法を紹介します。

「コードコメントWebレポート」を作成する

「コードコメントWebレポート」とは、プロジェクトで定義されているオブジェクト、インターフェイス、メンバ等の構造やコメントなどの情報を.htmファイルとして作成し、表示するためのVisual Studio .NETの機能です。ただし、Visual Studio 2005からはこの機能が無くなりましたので、Visual Studio .NET 2003以前でしか使用できません。

コードコメントWebレポートは、「ドキュメントコメントにより型の概要をXMLファイルに出力する」で紹介したドキュメントコメントのタグの一部を認識し、レポートに反映できます。認識するタグは、<summary>、<remarks>、<param>、<returns>、<newpara>（コメント内で新しい段落を開始します）です。ただし、ドキュメントコメントはC#だけで使用でき、VB.NETでは使用できません。

論より証拠、実際どのようなレポートが出力されるのか、見てみましょう。

「ドキュメントコメントにより型の概要をXMLファイルに出力する」と同じクラスライブラリを作成し、このコードコメントWebレポートを作成してみます。まず、Visual Studio .NETのメニュー「ツール｣-「Webページのビルドコメント」で「Webページのビルドコメントダイアログ」を表示します。ここでリポートを作成する場所（デフォルトではプロジェクトフォルダの下のCodeCommentReportフォルダ）等を指定し、「OK」をクリックすると、出来上がりです。

このようにして実際に作成されたコードコメントWebレポートは、このようになります。（正しく表示されませんが、これは作成されたHTMLのリンク先と実際のファイル名が大文字、小文字で異なり、正しくリンクされないためです。VS.NETの不具合と思われます。）

• 参考：
• コード レポートの作成

NDocを使用してヘルプを作成する

コードコメントWebレポートと同様のツールに、「NDoc」（日本語版）があります。NDocはHTMLだけでなく、HTML Helpファイル（.chm）も作成することができ、さらにVisual Studio .NET Helpフォーマット（HTML Help 2）など、様々なフォーマットにも対応しています。出力されるHTMLファイルは見慣れたMSDNスタイルなので、非常に分かりやすく、見やすいです。

NDocは「ドキュメントコメントにより型の概要をXMLファイルに出力する」で紹介したXMLドキュメントが必要になりますので、NDocを使用する前に作成しておきます。アセンブリファイルも必要ですので、ビルドしておく必要もあります。Visual Studio .NETの場合は、プロジェクトの設定の「XMLドキュメントファイル」にファイル名が指定されていれば、そのソリューションファイルをNDocの「New from Visual Studio Solution」で開くことにより、自動的にアセンブリファイルとXMLドキュメントファイルのパスが読み込まれ、「Select Assemblies to Document」のリストに追加されます。（Addボタンを押してアセンブリファイルとXMLドキュメントファイルのパスを指定することもできます。）後は「Build Documentation」をクリックするだけで、HTMLファイルとHTML Helpファイルがプロジェクトフォルダの下のdocフォルダ内に作られます（デフォルトの設定の場合）。

NDoc Ver 1.3-beta1aで作成したHTMLファイルをこちらに、日本語版 Ver 0.1のデフォルトの設定で作成したHTMLファイルをこちらに置いておきます。

Sandcastleを使用してヘルプを作成する

基本的に.NET Framework 2.0以降ではNDocは非対応となりました。しかし.NET Framework 2.0以降で使用できる同様のツールとして、マイクロソフトがSandcastleを公開しています。なお、この記事を書いている現在のバージョンは、「June 2007 Community Technology Preview (CTP)」です。

Sandcastleの使い方を簡単に説明しましょう。ここでは、Visual Studio 2005で「ドキュメントコメントにより型の概要をXMLファイルに出力する」と同じクラスライブラリを作成し、ヘルプファイルを作成するものとします。

1. Sandcastleをダウンロードし、インストールします。現在、こちらからダウンロードできます。
2. Visual Studio 2005をインストールしていない場合は、.NET Framework 2.0とHTML Help Workshopをインストールする必要があります。Visual Studio 2005をインストールしているのであれば、これらはインストールされているはずです。
3. こちらのバッチファイルをダウンロードし、適当なファイル名（拡張子は、「.bat」）で保存します。必ずバッチファイル内の「C:\Program Files\HTML Help Workshop」をhhc.exeのあるフォルダのパスに書き換えてください。なおこのバッチファイルは、Sandcastleをインストールした時に「Examples」フォルダ内にできる「build_Sandcastle.bat」を多少書き換えただけのものです。
4. Visual Studio 2005でヘルプを作成したいプロジェクトを開き、メニューの「プロジェクト」-「（プロジェクト名）のプロパティ」でプロジェクトのプロパティを開きます。
5. 「ビルド」タブを選択し、「XMLドキュメントファイル」を有効にし、ファイル名を「comments.xml」に変更します。ただし、フォルダは「出力パス」と同じにしてください。（例：「bin\Release\comments.xml」）
6. 「ビルドイベント」タブを選択し、「ビルド後に実行するコマンドライン」に

   "（バッチファイルのパス）" "$(TargetPath)" "$(TargetDir)" vs2005
   

   と記述します。「（バッチファイルのパス）」は先ほど作成したバッチファイルのパスに書き換えてください。
   「vs2005」の部分は、「hana」または「Prototype」とすることもできます。これにより、外観を変更できます。
7. プロジェクトをビルドすると、「bin\Release\」などの「出力パス」に自動的に「Output」というフォルダができ、その中に「test.chm」という名前でヘルプファイルが作成されます。
   「フリーズしたのでは？」と思うほどヘルプファイルが作成されるまで結構な時間がかかる場合があります。

上記のようにして作成されたヘルプ（ヘルプファイルの基になったHTMLファイル）は、次のようなものです。

• vs2005
• hana
• Prototype

SandcastleをGUIから使用するツール

Sandcastleには今のところ、GUIがありません。GUIによりSandcastleを使用するツールが幾つか公開されていますので、以下に紹介させていただきます。

• Sandcastle Help File Builder （The Code Project）
  現時点でもっともメジャーなツールです。
• SandcastleGUI
• GUI for Sandcastle
• SandCastle Builder

• 参考：
• Sandcastle - Microsoft CTP of a Help CHM file generator on the tails of the death of NDoc
• Sandcastle : Creating a Chm build using Sandcastle

その他のツール

上記で紹介したツール以外でもヘルプファイルの作成は、「Developer PowerToys」の「Custom Help Builder」（リンク切れ）でできるようです。

また、Doxygen（日本語）というツールも有名です。

現在は、これらのツールはどちらも.NET Framework 2.0には対応していないようです。

有料のツールとしては、A HotDocumentがあります。現在(2008/9/10)は、Visual Studio 2008に対応しているようです。

• 履歴：
• 2007/9/5 「Much improved NDoc for .Net 2.0」に関する情報を追記（コメントへのご指摘を参考にさせていただきました）。「Sandcastleを使用してヘルプを作成する」を追加。
• 2008/9/10 「Much improved NDoc for .Net 2.0」がリンク切れのため、修正。

（この記事は、「.NETプログラミング研究 第36号」で紹介したものです。）