| |
|
特集：ツールを使ったドキュメント作成技法（後編）
マイクロソフトも実施しているドキュメント作成技法
アバナード株式会社 市川 龍太（Microsoft MVP 2008 for XML）
2008/07/23 |
 |
|
●GhostDocとSandCastleを組み合わせたドキュメント作成技法
SandCastleを使ってCHM（コンパイル済みヘルプ）形式ファイルを生成する方法については、前編の「価値のある開発ドキュメントを効率的に作成するには？」で解説したが、実際の業務でこのようなドキュメントを作成する場合は、事前に決められた書式に合わせる必要がある場合が多い。例えば機能を説明する場合は機能説明タグを入れるとか、public型のメソッドの解説にはサンプル・コードを記述するなどである。
このような場合、Visual Studioのコード・エディタだけでは、毎回所定の書式に合わせてXMLドキュメント・コメントに手動で追記する必要があり、これはとても面倒な作業であった。しかしGhostDocを使用すれば、そういった面倒な作業が必要なくなるのである。
GhostDocで所定の書式でXMLドキュメント・コメントが生成されるようにするには、先ほど紹介した［Configuration］ダイアログの［Rules］タブに表示されている［Rules］リストの「Methods」などの該当の項目を選択して［Add］ボタンを押下し、そこで独自のルールを登録してやればよい。
 |
| 独自のルールを設定 |
| ［Configuration］ダイアログの［Rules］タブに表示されている［Rules］リストの「Methods」などの該当の項目を選択して［Add］ボタンを押下し、そこで独自のルールを登録しているところ。 |
| |
 |
［<any>］リンクを選択すると、［Edit Type Condition］ダイアログが表示され、「任意の条件にマッチした場合にのみ、特別なテキストを生成する」といった細かい設定が可能である。 |
| |
 |
XMLドキュメント・コメントの要素ごとに自動生成テキスト（この例では「パラメータの説明を記述」というテキスト）を設定可能。 |
| |
 |
この例では、<summary>要素に以下のテキストを設定している。
<p>[機能説明]</p>
<p>ここに機能説明を記述</p>
<p>[サンプル] </p>
<p>公開型メソッドの場合は、ここに使用サンプルを記述</p>
なお、改行を挿入したい場合は、入力欄の右端に表示される［...］ボタンをクリックし、そこで表示される［Edit Text Template］ダイアログの［Template Text］テキストボックスで改行すればよい。 |
|
上の画面の設定を行ったうえで、サンプル・プログラムのExecuteProcessメソッド上でGhostDocによるXMLドキュメント・コメントの自動生成を実行すると、設定した書式に従って次のようなXMLドキュメント・コメントが挿入されるはずである。
……省略……
/// <summary>
/// <p>[機能説明]</p>
/// <p>ここに機能説明を記述</p>
/// <p>[サンプル] </p>
/// <p>公開型メソッドの場合は、ここに使用サンプルを記述</p>
/// </summary>
/// <param name="parameter">パラメータの説明を記述</param>
public void ExecuteProcess(string parameter)
{
}
……省略…… |
|
| GhostDocにより自動的に追加されたXMLドキュメント・コメント（独自のルール） |
| 太字部分がGhostDocにより自動的に追加されたXMLドキュメント・コメントである。 |
最後にSandCastleを使用してCHM形式ファイルを生成した例を以下に示す。
 |
| GhostDocとSandCastleを組み合わせて作成したCHM形式ファイルの例 |
このようにGhostDocとSandCastleを組み合わせて使うことで、任意の書式でCHM形式ファイルを自動生成することができる。SandCastleが生成するCHM形式ファイルは、主にクラス仕様書やインターフェイス仕様書などの用途で使われることが多いため、GhostDocによる柔軟な書式のカスタマイズはとても有効なドキュメント作成技法だろう。
それでは、次にpatterns & practices Documentation Tools（以下Documentation Tools）の解説に移る。
Insider.NET 記事ランキング
本日
月間
