Sandcastleにてヘルプを生成する場合、まずページにあたるHTMLを生成します。
HTMLを生成するまでの流れ
HTMLを生成するまでの流れは下図の通りです。
|
HTMLを生成するまでの流れ |
なお、実際にヘルプを生成する際には作業フォルダに必要なファイルをコピーしたりといった細かい手順も必要になります。この図ではそのような流れは割愛して、Sandcastleの主要なプログラムの動作と入出力が明確になるように描画しています。
(1)Visual Studioによるビルド
まず、XMLドキュメントコメントを記述したソースコードをVisual Studioでコンパイルします。C#プロジェクトの場合、プロジェクトプロパティのビルドタブで「XMLドキュメントファイル」にチェックを入れておきます。インテリセンス時の説明としても利用されるので、ファイル名は「アセンブリ名.xml」としておけば良いでしょう(VBの場合は、既定の設定でXMLドキュメントが出力されるようになっていますが、もし出力されない場合はコンパイルタブの「XMLドキュメントファイルを出力する」にチェックを入れてください)。
|
プロジェクトのプロパティでXMLドキュメントを出力するように設定(C#) |
この状態でビルドを行うと、/doc:オプションが付加されたコンパイルが行われ、アセンブリ(*.exe/*.dll)と共にXMLドキュメントが生成されます。
Sandcastleが行う作業
Visual Studioのビルドによって、2つのファイルが生成されました。1つがアセンブリで、もう1つがXMLドキュメントファイルです。この2つのファイルを再び結合するのがSandcastleの仕事ともいえます。というのも、実行ファイルであるアセンブリにはクラスやメンバのすべての型情報が含まれていますが、XMLドキュメントコメントは含まれていません。逆に、XMLドキュメントにはXMLドキュメントコメントは含まれていますが、クラスやメンバの型情報がありません。そこで、Sandcastleには、これらの2つのファイルから必要な情報を取り出し、1つのHTMLファイルを生成するという機能を備えています。
初めてSandcastleを使う場合
もし、初めてヘルプドキュメントを作る場合は、後編の最後に紹介するSandcastle Help File Builderから試したほうが簡単で良いでしょう。というのも、Sandcastleにはコマンドラインで動作するプログラムは含まれていますが、リッチなUIを持つプログラムは含まれていません。これ以降紹介していくコマンドラインプログラムを操作するには多少の慣れが必要なため、とりあえずSandcastleを試してみたいという方には、直観的なユーザーインタフェースを持つSandcastle Help File Builderから試してみたほうが分かりやすいでしょう。
