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

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

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

 前編では、価値のあるドキュメントを作成するためのコツと、効率的にドキュメントを作成するためのツールとして「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ドキュメント・コメントの書式を自由に設定できるのである。


 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