Top > プログラミング > .NET Tips > Visual Studio

自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成する

この記事への評価、コメント

自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成する

自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成するのは面倒ですが、それを自動で作成してくれるツールがあります。これらのツールを使えば、ソースコードファイルに記述されたドキュメントコメントを基にして、MSDNのようなヘルプやHTMLを簡単に作成できます。ここではこのようなツールを幾つか紹介します。

なおここで紹介しているツール（「コードコメントWebレポート」以外）には、ソースコードファイルのドキュメントコメントを出力したXMLファイルが必要ですので、その作り方がわからないという場合は、まず「ドキュメントコメントにより型の概要をXMLファイルに出力する」をご覧ください。

Sandcastle Help File Builderを使用してヘルプを作成する

現在最もメジャーなツールが、「Sandcastle Help File Builder（SHFB）」（現在のバージョンは、1.9.7.0）です。以前はマイクロソフトが「Sandcastle」というツールを開発していましたが、それが終了し、現在ではSandcastleのGUIであるSHFBが引き継いでいます。

Sandcastle Help File Builder

SHFBのインストール方法は「Sandcastle Help File Builder Documentation - Installation Instructions」で説明されていますが、SHFB以外にインストールが必要なもの（あるいは、インストールした方がよいもの）が多々あります。しかしインストーラの指示に従えば必要なものがインストールできますので、いきなりインストーラを起動してしまってよいでしょう。

ちなみに、「.NET Framework 4.0」と「Sandcastle tools」は必ずインストールする必要があります。SHFBが作成できるヘルプファイルの種類は、HTML Help 1（Microsoft Compiled HTML Help、.chm)、MS Help 2 (Visual Studio .NET Helpフォーマット、.HxS)、MS Help Viewer (Microsoft ヘルプビューアー、.mshc)、ASP.NET HTML (.html, .aspx, .php ...)ですが、HTML Help 1を作成するには「HTML Help Workshop」を、MS Help 2を作成するには「Visual Studio 2005 SDK v4.0」か「Visual Studio 2008 SDK v1.0」をインストールする必要があります。

インストールが成功したとして、SHFBの簡単な使い方を説明します。

「Sandcastle Help File Builder GUI」を起動後、まずは、新しいプロジェクトを作成します。メニューの「File」-「New Project」を選択すると、「Save New Help Project As」というダイアログが表示されますので、保存場所を指定します。

次に「Documentation Source」を追加します。画面右上の「Project Explorer」にある「Documentation Sources」を右クリックしてコンテキストメニューを表示し、「Add Documentation Source」を選択します。「Select the documentation source(s)」というダイアログが表示されますので、ここでヘルプを作成したいライブラリファイル（.dll、.winmd）、実行ファイル（.exe）、XMLドキュメントファイル（.xml）、Visual Studioソリューションファイル（.sln）、Visual Studioプロジェクトファイルのいずれかを選択します。

もし必要ならば、参照しているアセンブリを「References」に追加します。

そして、画面左側の「Project Properties」を適当に変更します。とりあえず変更すべき設定は、「Build」タブの「Framework Version」と、「Help File」タブの「Help title」位です（「Help file language」を「Japanese(Japan)」にしてもほとんど日本語化されません）。デフォルトでは、<summary>などの要素が無いとヘルプに赤い警告文が表示されますが、これを消す場合は、「Missing Tags」タブでチェックを外します。

準備が整ったら、メニューから「Documentation」-「Build Project」を選択して、ヘルプファイルを作成します。ビルドを開始すると「Build Output」タブが開き、進行状況が表示されます。ビルドが終わると、デフォルトでは、「Save New Help Project As」で指定したフォルダに「Help」というフォルダができ、その中にヘルプファイルとログファイルが作成されます。

「Visual Studio Integration Package」をインストールした時は、Visual Studio（2010以降）でヘルプを作成することもできます。その場合は、「新しいプロジェクト」ダイアログ（メニューの「ファイル」-「新規作成」-「プロジェクト」で表示）の「Documentation」タブにある「Sandcastle Help File Builder Project」を選択することで、SHFBのプロジェクトを作成できます。後は先ほどの「Sandcastle Help File Builder GUI」とほぼ同じ操作です。プロジェクトをビルドすると、ヘルプが作成されます。

このような方法で作成したヘルプファイルを以下のリンク先に置いておきます（ZIP圧縮されています）。

「Documentation Source」に追加したXMLファイル（この記事を書いている時点では、「ドキュメントコメントにより型の概要をXMLファイルに出力する」の具体例で紹介しているクラスライブラリと同じです。）
SHFBで作成されたヘルプ（.chm）ファイル
ヘルプをコンパイルする際に使用されたHTMLファイル

Sandcastleを使用してヘルプを作成する

以下にSandcastleを単独で使用する方法を説明しますが、バージョンが「June 2007 Community Technology Preview (CTP)」の時の情報ですので、昔の情報であることをご了承ください。

ここでは、以下のようなクラスライブラリ「ClassLibrary1」があるとして、このヘルプファイルを作成します。

コードを隠すコードを選択

using System;

namespace ClassLibrary1
{
    /// <summary>
    /// テストのクラスです。
    /// </summary>
    /// <exception cref="System.Exception">
    /// ここには例外の説明を書きます。
    /// </exception>
    public class TestClass
    {
        /// <summary>
        /// 現在の合計値を保存するフィールド
        /// </summary>
        private int _sum;

        /// <summary>
        /// 現在の合計値を取得設定します。
        /// </summary>
        /// <value>現在の合計値</value>
        public int Sum
        {
            get {return _sum;}
            set {_sum = value;}
        }

        /// <summary>
        /// <c>TestClass</c>クラスの新規インスタンスを初期化し、
        /// 指定した数を合計値に設定します。
        /// </summary>
        /// <param name="val">初期値</param>
        public TestClass(int val)
        {
            _sum = val;
        }

        /**
        <summary>
        TestClassクラスの新規インスタンスを初期化します。
        </summary>
        */
        public TestClass()
        {
            _sum = 0;
        }

        /// <summary>
        /// 指定した値を合計値に加算します。
        /// </summary>
        /// <param name="val">加算する整数</param>
        /// <returns>現在の合計値</returns>
        /// <remarks>
        /// <c>Plus</c>メソッドの
        /// <paramref name="val"/>パラメータで加算する整数を指定します。
        /// <para>合計値は<see cref="Sum"/>で
        /// 取得できます。</para>
        /// </remarks>
        /// <example>Plusメソッドの使用コード例です。
        /// <code>
        /// class MainClass
        /// {
        ///     public static void Main()
        ///     {
        ///         TestNP.TestClass tc = new TestNP.TestClass(100);
        ///         tc.Plus(10);
        ///     }
        /// }
        /// </code>
        /// </example>
        /// <seealso cref="System.Int32">Int32構造体</seealso>
        /// <seealso cref="Minus"/>
        /// <permission cref="System.Security.PermissionSet">
        /// このメソッドへは誰でもアクセスできます。</permission>
        public int Plus(int val)
        {
            _sum += val;
            return _sum;
        }

        /// <include file='include.xml' 
        /// path='TestDocs/TestMembers[@name="Minus"]/*' />
        public int Minus(int val)
        {
            _sum -= val;
            return _sum;
        }
    }
}

また、「include.xml」の中身は次のようになっているものとします。

<?xml version="1.0" encoding="utf-8" ?>
<TestDocs>
<TestMembers name="Minus">
<summary>
指定した値を合計値から除算する。
</summary>
<param name="val">除算する値。</param>
<returns>現在の合計値。</returns>
</TestMembers>
</TestDocs>

それでは、Sandcastleでヘルプファイル(.chm)を作成する手順を示します。

「Sandcastle - Documentation Compiler for Managed Class Libraries」からSandcastleをダウンロードし、インストールします。
Visual Studio 2005をインストールしていない場合は、.NET Framework 2.0とHTML Help Workshopをインストールする必要があります。Visual Studio 2005をインストールしているのであれば、これらはインストールされているはずです。
こちらのバッチファイル（ZIP圧縮されています）をダウンロードし、適当な場所に展開します。必ずバッチファイル内の「C:\Program Files\HTML Help Workshop」をhhc.exeのあるフォルダのパスに書き換えてください。なおこのバッチファイルは、Sandcastleをインストールした時に「Examples」フォルダ内にできる「build_Sandcastle.bat」を多少書き換えただけのものです。
Visual Studio 2005でヘルプを作成したいプロジェクトを開き、メニューの「プロジェクト」-「（プロジェクト名）のプロパティ」でプロジェクトのプロパティを開きます。
「ビルド」タブを選択し、「XMLドキュメントファイル」を有効にし、ファイル名を「comments.xml」に変更します。ただし、フォルダは「出力パス」と同じにしてください。（例：「bin\Release\comments.xml」）
「ビルドイベント」タブを選択し、「ビルド後に実行するコマンドライン」に
```
"（バッチファイルのパス）" "$(TargetPath)" "$(TargetDir)" vs2005
```
と記述します。「（バッチファイルのパス）」は先ほど作成したバッチファイルのパスに書き換えてください。
「vs2005」の部分は、「hana」または「Prototype」とすることもできます。これにより、外観を変更できます。
プロジェクトをビルドすると、「bin\Release\」などの「出力パス」に自動的に「Output」というフォルダができ、その中に「test.chm」という名前でヘルプファイルが作成されます。
「フリーズしたのでは？」と思うほどヘルプファイルが作成されるまで結構な時間がかかる場合があります。

ちなみに、上記のようにして作成されたヘルプ（ヘルプファイルの基になったHTMLファイル）を以下の場所に置いておきます（ZIP圧縮されています）。

SandcastleのGUIツール

「Sandcastle Help File Builder」以外にもSandcastleのGUIツールが幾つかありますので、紹介しておきます。しかしこれらは皆古いため、特別な理由がなければ「Sandcastle Help File Builder」を使うべきです。

SandcastleGUI（リンク切れ）
GUI for Sandcastle
SandCastle Builder

NDocを使用してヘルプを作成する

.NET Framework 1.1以前は、「NDoc」（日本語版）が定番でした。しかしNDocは.NET Framework 2.0からは使用できなくなりました。以下にNDocの使い方を簡単に説明します。

NDocは「ドキュメントコメントにより型の概要をXMLファイルに出力する」で紹介したXMLドキュメントが必要になりますので、NDocを使用する前に作成しておきます。アセンブリファイルも必要ですので、ビルドしておく必要もあります。Visual Studio .NETの場合は、プロジェクトの設定の「XMLドキュメントファイル」にファイル名が指定されていれば、そのソリューションファイルをNDocの「New from Visual Studio Solution」で開くことにより、自動的にアセンブリファイルとXMLドキュメントファイルのパスが読み込まれ、「Select Assemblies to Document」のリストに追加されます（Addボタンを押してアセンブリファイルとXMLドキュメントファイルのパスを指定することもできます）。後は「Build Documentation」をクリックするだけで、HTMLファイルとHTML Helpファイルがプロジェクトフォルダの下のdocフォルダ内に作られます（デフォルトの設定の場合）。

NDoc Ver 1.3-beta1aで作成したHTMLファイルと、日本語版 Ver 0.1のデフォルトの設定で作成したHTMLファイルを以下のリンク先に置いておきます（ZIP圧縮されています）。

.NET Framework 2.0以降でNDocを使用する

先述した通り、NDocは.NET Framework 2.0以降では使用できなくなりました。しかしNDoc Version 1.3.1をインストール後に、「Much improved NDoc for .Net 2.0」（現在リンク切れ）で公開されていた"ndoc-bin-1.3.1-v16.zip"の中身を上書きすることにより、.NET Framework 2.0でも使えるようになります。現在ダウンロードできる場所は、Googleで"ndoc-bin-1.3.1-v16.zip"を検索してみてください。

また、NDocを基にして作られた「NDoc 2.0 Alpha」や「NDoc 2005」なども公開されています。

その他のツール

上記で紹介したツール以外では、以下のようなものがあります。

「Custom Help Builder」（リンク切れ）は、.NET Framework 2.0に対応しておらず、更新されていません。
「Doxygen」（日本語）は有名なツールですが、.NET Frameworkではあまり使われません。
有料のツールとしては、A HotDocumentなどがあります。

Visual Studioで「コードコメントWebレポート」を作成する

Visual Studio .NETには「コードコメントWebレポート」という機能があり、プロジェクトで定義されているオブジェクト、インターフェイス、メンバ等の構造やコメントなどの情報を.htmファイルとして作成することができました。ただし、Visual Studio 2005からはこの機能が無くなりましたので、Visual Studio .NET 2003以前でしか使用できません。

コードコメントWebレポートは、「ドキュメントコメントにより型の概要をXMLファイルに出力する」で紹介したドキュメントコメントのタグの一部を認識し、レポートに反映します。認識するタグは、<summary>、<remarks>、<param>、<returns>、<newpara>（コメント内で新しい段落を開始します）です。ただしVisual Studio .NET 2003以前では、ドキュメントコメントはC#だけで使用でき、VB.NETでは使用できません。

実際どのようなレポートが出力されるのか、見てみましょう。ここでは、上記「Sandcastleを使用してヘルプを作成する」で使用したクラスライブラリ「ClassLibrary1」のコードコメントWebレポートを作成してみます。

まず、Visual Studio .NETのメニュー「ツール｣-「Webページのビルドコメント」で「Webページのビルドコメントダイアログ」を表示します。ここでリポートを作成する場所（デフォルトではプロジェクトフォルダの下のCodeCommentReportフォルダ）等を指定し、「OK」をクリックすると、出来上がりです。

このようにして実際に作成されたコードコメントWebレポートを以下のリンク先に置いておきます（ZIP圧縮されています）。正しく表示されませんが、これは作成されたHTMLのリンク先と実際のファイル名が大文字、小文字で異なり、正しくリンクされないためです。VS.NETの不具合と思われます。

「ClassLibrary1」のコードコメントWebレポート

参考：
コードレポートの作成

XSLTを使用してHTMLに変換する

XSLTスタイルシートを使えば、ツールを使うことなく、XMLをHTMLに変換してWebブラウザで表示できます。

XMLコメントファイルをXSLTスタイルシートで見やすくするための方法が、MSDNの「Introducing the Visual Studio .NET Lab Series」の「Lab 2: XML Comments」で紹介されています。以下に、「Lab 2: XML Comments」の方法をごく簡単に説明します。

まずXSLファイルを用意し（下のリンク先に置いておきます）、このXSLファイルをXMLファイルと同じフォルダに置き、XMLファイルの先頭の

<xml version="1.0"?>

と

<doc>

の間に

<xml-stylesheet href="doc.xsl" type="text/xsl"?>

を書き足して、おしまいです。こうしてできたXMLファイルを下のリンク先に置いておきます（ZIP圧縮されています）。

上記のXSLファイルはxsl:script要素を使っていますが、これを使わないXSLファイルの例が「Simple XSLT stylesheet for Visual Studio .NET XML documentation」にあります。このXSLファイルを日本語化したものを下に置いておきます（ZIP圧縮されています）。

履歴：
2007/9/5 「Much improved NDoc for .Net 2.0」に関する情報を追記（コメントへのご指摘を参考にさせていただきました）。「Sandcastleを使用してヘルプを作成する」を追加。
2008/9/10 「Much improved NDoc for .Net 2.0」がリンク切れのため、修正。
2013/4/29 「Sandcastle Help File Builderを使用してヘルプを作成する」を追加。「XSLTを使用してHTMLに変換する」を「ドキュメントコメントにより型の概要をXMLファイルに出力する」から移動。
2017/3/2 サンプルのヘルプファイル等をZIP書庫にした。

（この記事は、「.NETプログラミング研究第36号」で紹介したものです。）

注意：この記事では、基本的な事柄の説明が省略されているかもしれません。初心者の方は、特に以下の点にご注意ください。

「???を参照に追加します」の意味が分からないという方は、こちらをご覧ください。
Windows Vista以降でUACが有効になっていると、ファイルへの書き込みに失敗する可能性があります。詳しくは、こちらをご覧ください。
.NET Tipsをご利用いただく際は、注意事項をお守りください。

共有する

この記事への評価

この記事の評価を見る

この記事へのコメント

この記事へのコメントの一覧を見る

この記事に関するコメントを投稿するには、下のボタンをクリックしてください。投稿フォームへ移動します。通常のご質問、ご意見等は掲示板へご投稿ください。

設定

.NET Tips

掲示板最新情報

Translate

その他