特集:ツールを使ったドキュメント作成技法(後編)

マイクロソフトも実施しているドキュメント作成技法

アバナード株式会社 市川 龍太(Microsoft MVP 2008 for XML)
2008/07/23
Page1 Page2 Page3

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)の解説に移る。


 INDEX
  [特集]
  ツールを使ったドキュメント作成技法(前編)
  価値のある開発ドキュメントを効率的に作成するには?
    1. アジャイル・ドキュメントとは何か?
    2. 価値のあるドキュメントを作成するコツ
    3. ツールを使ったドキュメントの作成技法
 
  ツールを使ったドキュメント作成技法(後編)
  マイクロソフトも実施しているドキュメント作成技法
    1. 柔軟なXMLドキュメント・コメントを生成する「GhostDoc」
  2. GhostDocとSandCastleを組み合わせたドキュメント作成技法
    3. マイクロソフトも活用する「patterns & practices Documentation Tools」


Insider.NET フォーラム 新着記事
  • 第2回 簡潔なコーディングのために (2017/7/26)
     ラムダ式で記述できるメンバの増加、throw式、out変数、タプルなど、C# 7には以前よりもコードを簡潔に記述できるような機能が導入されている
  • 第1回 Visual Studio Codeデバッグの基礎知識 (2017/7/21)
     Node.jsプログラムをデバッグしながら、Visual Studio Codeに統合されているデバッグ機能の基本の「キ」をマスターしよう
  • 第1回 明瞭なコーディングのために (2017/7/19)
     C# 7で追加された新機能の中から、「数値リテラル構文の改善」と「ローカル関数」を紹介する。これらは分かりやすいコードを記述するのに使える
  • Presentation Translator (2017/7/18)
     Presentation TranslatorはPowerPoint用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)
- PR -

注目のテーマ

Insider.NET 記事ランキング

本日 月間
ソリューションFLASH