ヘルプドキュメントの作成
チームで開発をしている時に、共通部品のドキュメントがあれば良いのにと思ったことはありませんか。また、MSDNのようなAPIリファレンスを作成しなければいけない状況になったことはありませんか。 このような時にWordやExcelを使ってヘルプドキュメントを書くとなると、プログラムとの整合性を保つ必要があり多くの工数がかかります。そこで本稿では、ソースコードに記述したクラスやメンバの説明から、リファレンス形式のヘルプドキュメントを生成できる「Sandcastle(サンドキャッスル)」というツールについて紹介します。
構成について
本稿では、Sandcastleというソフトウェアを使って、.NETのソースコードに記述したコメントからヘルプファイルを生成する方法について紹介します。この前編では、以下の内容について紹介します。
・Sandcastleの概要とXMLドキュメントコメントの書き方
・SandcastleによるHtmlの生成
そして後編では、以下の内容について紹介します。
・Sandcastleによるヘルプの生成
・Sandcastleの実行方法とツールの紹介
それでは、Sandcastleの概要から紹介していきましょう。
Sandcastleとは
Sandcastleとは、Microsoftから無償で提供されているドキュメントコンパイラです。このソフトウェアを利用すると、C#やVBのコードに記述したXMLドキュメントコメント(XMLコードコメント)から、リファレンスマニュアルを容易に生成することができます。
XMLドキュメントコメントの書き方
リファレンスマニュアルの元となる「XMLドキュメントコメント」は、ソースコードのコメントとして記述します。C#では「///(スラッシュ3つ)」から始め、VBでは「'''(シングルクォーテーション3つ)」から始めます。その後ろに、以下のような特定のXMLタグを使って、クラスまたはメンバの詳細を記述していきます。
XMLドキュメントコメントの主要なタグ
| タグ名 | タグの説明 |
|---|---|
| <summary> | クラスまたはメンバの説明 |
| <param> | 引数の説明。name属性に引数名を記述 |
| <returns> | 戻り値の説明 |
| <remarks> | 解説 |
| <example> | 例を記述。サンプルコードは<code>タグ(lang属性、escaped属性あり) |
| <seealso> | 参照クラスやメンバ。cref属性でリンク対象を記述 |
XMLドキュメントコメントの例
XMLドキュメントコメントの例を見てみましょう。ここでは、簡単な計算を行うCalcクラスにXMLドキュメントコメントを記述しています。
|
XMLドキュメントコメントの書き方の例 |
ヘルプファイルの出力例
このサンプルでヘルプドキュメントを生成した場合、次のような形式で出力されます。
|
出力されたヘルプ(クラス部) |
|
出力されたヘルプ(メソッド部) |
ソースコードに書いたコメントが、ヘルプドキュメントに反映されていることがわかります。各タグが、どこに出力されるかを把握しておくと、ドキュメントをうまく記述できるでしょう。
