| |
 |
特集：ツールを使ったドキュメント作成技法（後編）
マイクロソフトも実施しているドキュメント作成技法
アバナード株式会社 市川 龍太（Microsoft MVP 2008 for XML）
2008/07/23 |
|
前編では、価値のあるドキュメントを作成するためのコツと、効率的にドキュメントを作成するためのツールとして「SandCastle」を解説した。後編では、そのほかのドキュメンテーション支援ツールとして「GhostDoc」と「patterns & practices Documentation Tools」について解説する。
■柔軟なXMLドキュメント・コメントを生成する「GhostDoc」
GhostDocは、あらかじめ設定した任意の書式にのっとったXMLドキュメント・コメントを生成してくれるVisual Studioアドインであり、MSDNマガジンにて「すべての開発者がダウンロードするべきVisual Studioアドイン（Visual Studio Add-Ins Every Developer Should Download Now）」として紹介されたことがあるほどポピュラーかつ有用なツールである。
GhostDocの使い方について解説しよう。まず以下のサイトからGhostDocのインストーラをダウンロードする（本稿では、Visual Studio 2008を使用するため、「GhostDoc Version 2.1.3 for Visual Studio 2008」をダウンロードした）。
ダウンロードした.zipファイルを解凍し、msi（Windowsインストーラ）形式ファイル（本稿では「GhostDoc2.1.3.msi」）を実行するとGhostDocがインストールされる。
その後にVisual Studio 2008を起動すると、初回時のみGhostDocの初期設定を行うためのウィザード（ダイアログ）が表示される。このウィザードでは、ショートカット・キー（Hotkey）の設定やルールの構成（新規作成かインポート）などを行う。
 |
| 初期設定ウィザードにおけるショートカット・キーの設定 |
| GhostDocのインストール後にVisual Studio 2008を起動すると、初回時のみGhostDocの初期設定を行うためのダイアログが表示される。 |
| |
 |
［Hotkey］でGhostDocを実行するショートカット・キー（この例では［Ctrl＋Shift＋D］キー）を選択して、［Assign］ボタンをクリックして登録する。 |
|
ウィザードが完了してGhostDocが完全にインストールされると、次の画面のように、Visual StudioのIDEの［ツール］メニューに［GhostDoc］メニューが追加される。
 |
| Visual Studioに追加された［ツール］−［GhostDoc］メニュー |
次にサンプル用にコンソール・アプリケーションを新規作成し、CustomBizLogicクラスを作成してみよう（以下では開発言語としてC#を使用する）。CustomBizLogicクラスのコード内容は次のとおりだ。
namespace GhostDocSample
{
class Program
{
static void Main(string[] args)
{
}
}
public class CustomBizLogic
{
public void ExecuteProcess(string parameter)
{
}
}
} |
|
| CustomBizLogicクラスのコード内容 |
ここでCustomBizLogicクラスのExecuteProcessメソッド内に入力カーソルを置いてから、先ほどの初期設定ウィザードで割り当てたショートカット・キー（本稿では［Ctrl］＋［Shift］＋［D］キー）を押下すると、次のコード例のように、XMLドキュメント・コメントが自動的に追加される。なお、ショートカット・キーではなく、メニュー・バーの［ツール］−［GhostDoc］−［Document this］を選択してもよい。
……省略……
/// <summary>
/// Executes the process.
/// </summary>
/// <param name="parameter">The parameter.</param>
public void ExecuteProcess(string parameter)
{
}
……省略…… |
|
| GhostDocにより自動的に追加されたXMLドキュメント・コメント（標準のルール） |
| 太字部分がGhostDocにより自動的に追加されたXMLドキュメント・コメントである。 |
GhostDocは入力カーソルが置かれている場所を自動的に認識し、その定義に合わせてXMLドキュメント・コメントを自動生成する。これだけであればVisual Studioのコード・エディタでも、C#では「///」、VBでは「'''」のようにコメント記号を3つ続けて記述することで、同様のXMLドキュメント・コメントを生成できるため、GhostDocを使うメリットがあまりないように思えるかもしれない。
しかしGhostDocの優れているところは、この自動生成されるXMLドキュメント・コメントの書式を柔軟にカスタマイズできるところにある。カスタマイズは、メニュー・バーの［ツール］−［GhostDoc］−［Configure GhostDoc］を選択すると表示される［Configuration］ダイアログから行える。
 |
| GhostDocの［Configuration］ダイアログ |
このダイアログからクラスやメソッドの要素別にXMLドキュメント・コメントの書式を自由に設定できるのである。
Insider.NET 記事ランキング
本日
月間
