前回は Sandcastle と Sandcastle Help File Builder のインストールができたとこまで。 今回は実際にヘルプファイルを出力してみる。

まずは、ソースコードに XML ドキュメントコメントを入れる。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace ConsoleApplication1
{
    /// <summary>
    /// Class1 クラスの概要。
    /// </summary>
    /// <remarks>
    /// 長い説明。
    /// </remarks>
    class Class1
    {
        /// <summary>
        /// Prop1 プロパティの概要。
        /// </summary>
        public string Prop1 { get; set; }

        /// <summary>
        /// クラスのコンストラクタの説明。
        /// </summary>
        public Class1()
        {
        }

        /// <summary>
        /// Method1 メソッドの概要。
        /// </summary>
        /// <param name="x">x パラメータの説明。</param>
        /// <param name="s">s パラメータの説明。</param>
        /// <returns>戻り値の説明。</returns>
        public long Method1(int x, string s)
        {
            return 0;
        }

        /// <summary>
        /// Method2 メソッドの概要。
        /// </summary>
        /// <param name="x">x パラメータの説明。</param>
        /// <param name="s">s パラメータの説明。</param>
        /// <returns>戻り値の説明。</returns>
        public long Method2(int x, string s)
        {
            return 0;
        }
    }
}
次に、XML ドキュメントコメントから XML ファイルを生成する。Visual Studio のプロジェクトのプロパティダイアログを開き（メニューの[プロジェクト] - [プロパティ] などから）、[ビルド]タブの[XMLドキュメントファイル]にチェックを入れる。出力パスとXML ドキュメントファイルの名称は適当でよい。ここではデフォルトのままとした。これにより、ビルドするとき、常に XML ファイルも作られるようになる。

次は、ビルドしてできた dll とXML ファイルからヘルプファイルを生成する。スタートメニューから Sandcastle Help File Builder GUI を起動する。

新しいプロジェクトを作る場合は、メニュー[File]-[New Project] を選ぶ。自動的にプロジェクトファイルの保存場所を選ぶダイアログが出るので、希望の場所を選ぶ。

メインウィンドウの右側に Project Explorer が表示されているので、Documentation Sources で右クリックし、ビルドしてできた dll とXML ファイルを追加する。dll とXML ファイルが拡張子が違うだけなら、どちらかを追加するだけでいいようだ。

メインウィンドウの左側でお好みの設定する。

今回は変更した設定は以下のとおり。
・[Build] タブ - [Build these help file formats]
　　出力するヘルプファイルのフォーマット。今回は HTML Help1 (CHM) とした。
・[Help File] タブ- [Help title]
　　ヘルプファイル内に表示するタイトル。
・[Help File] タブ- [Help file name]
　　ヘルプファイルのファイル名。
・[Help File] タブ- [Help file language]
　　ヘルプファイル内の言語。今回は Japanese （Japan） を選んだが、日本語化が不完全な模様。
　　以下の方が、日本語化ファイルを公開されておられる。感謝。
　　http://d.hatena.ne.jp/tueda_wolf/20120717/p3
・[Help File] タブ- [Presentation style]
　　ヘルプファイルの表示スタイル。今回は VS2010 を選らんだ。

そして、メニュー[Documentation]-[Buid Project]を選ぶと、ドキュメントが出力される。 と思ったら以下のようなエラーが出て、ドキュメントが出力されない。
SHFB: Error BE0033: No APIs found to document.  See error topic in help file for details.
どうも、プロジェクト内に public なクラスが最低ひとつは必要なようだ。テストプロジェクトだったので、上の Class1 を public にしていなかった。。。その点を修正して、ビルドし直すと、ヘルプファイルが出力された。 sandcastle-chm