Sandcastle Help File Builderを使ってみた。その２。

前回のエントリーに引き続いて、C#のドキュメントコメントを用いたドキュメント生成についてです。
今回はドキュメントコメントからどのようなドキュメントが出力されるか試してみました。

まず、以下のようなサンプルコードを書きました。
ドキュメントコメントの各タグの出力結果を確認するためのコードなので、処理内容は適当です。

/// <summary>
/// ここにクラスの概要。
/// </summary>
public class Program
{
    /// <summary>
    /// ここにプロパティの概要。
    /// </summary>
    /// <value>ここに値の説明。</value>
    public int MyProperty { get; set; }

    /// <summary>
    /// ここに概要を記述。
    /// </summary>
    /// <param name="args">引数。</param>
    public static void Main(string[] args)
    {
    }

    /// <summary>
    /// ここに概要を記述。
    /// </summary>
    /// <remarks>
    /// ここに詳しい説明。
    /// <para>段落を区切る場合はparaタグを使う。</para>
    /// <see cref="System.Int32"/>
    /// </remarks>
    /// <param name="value1">値1。</param>
    /// <param name="value2">値2。</param>
    /// <returns>value1にvalue2を加えた結果を返します。</returns>
    /// <exception cref="System.ArgumentOutOfRangeException">
    /// 引数が範囲外です。
    /// </exception>
    /// <exception cref="System.ArgumentNullException">
    /// 引数がnullです。
    /// </exception>
    /// <example>
    /// ここに使用例を記述。コード例はcodeタグ内に記述。
    /// <code>
    /// int result;
    /// result = Program.Add&lt;int, int&gt;(10, 5);
    /// </code>
    /// </example>
    /// <seealso cref="Program.Main"/>
    public static int Add(int value1, int value2)
    {
        return Program.AddHelper<int, int>(value1, value2);
    }

    /// <summary>
    /// Public以外は出力されない。
    /// </summary>
    /// <typeparam name="T1">***の型。</typeparam>
    /// <typeparam name="T2">***の型。</typeparam>
    /// <param name="value1">値1。</param>
    /// <param name="value2">値2。</param>
    /// <returns>value1にvalue2を加えた結果を返します。</returns>
    internal static int AddHelper<T1, T2>(int value1, int value2)
    {
        return value1 + value2;
    }
}

このコードをSandcastle Help File Builderで出力すると以下のようなドキュメントが作成されます。

クラスのドキュメント

MyPropertyのドキュメント

Add()のドキュメント

AddHelper()のドキュメント

ドキュメントコメント記述時の注意点
・タグの記述順は生成されるドキュメントレイアウトにも反映されるため、
   VSで///を入力したときの自動挿入の順序に従った方がmsdnと同じレイアウトになって○。
・ドキュメントコメント内の<>は&lt;&gt;で記述する。

実際に出力してみると各タグの役割がよく分かりますね。
振り返ってみると、今まで場所違い(タグ違い?)なコメントを記述をしていた気がします。。。

ちゃんと各タグの役割を理解して、より良いドキュメントが作成されるようなコメントを
記述するようにしましょう。じゃないと、わざわざドキュメントコメントで記述している意味がないですからね～。