• ドキュメントコメントにより型の概要をXMLファイルに出力する
  • スマートコメント編集によって、自動的に挿入する
  • IntelliSenseで説明を表示する
  • オブジェクトブラウザで説明を確認する
  • XMLファイルに出力する
  • ドキュメントコマンド用タグ一覧
  • 推奨タグを使った具体例
  • Visual Studio 2003以前のVB.NETでドキュメントコメントを作成する

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

ドキュメントコメントにより型の概要をXMLファイルに出力する

Visual Studioには、XML形式のドキュメントコメント（コードコメント、XMLスタイルコメント）をソースコードに記述することによって、クラスやメンバなどの型の説明を記述できる機能があります。この機能を使えば、Visual StudioのIntelliSenseやオブジェクトブラウザで、自作のクラス等の説明を表示させることができます。

さらにC#やVB.NETのコンパイラには、ドキュメントコメントをXMLファイルとして出力する機能があります。このXMLファイルとSandcastleやNDocなどのツール使えば、自作ライブラリの仕様書（リファレンス）を簡単に作成することができます。

ここでは、このドキュメントコメントについて説明します。

スマートコメント編集によって、自動的に挿入する

Visual Studioでは、「スマートコメント編集」と呼ばれる機能により、簡単にドキュメントコメントを挿入することができます。ただしVB.NETの場合は、Visual Studio 2003以前ではこの機能を使用することはできません。（Visual Studio 2003以前で使用する方法は、後述します。）

例えばクラスライブラリプロジェクト「ClassLibrary1」に以下のようなクラス「TestClass」があったとします。

Public Class TestClass

    Public Shared Function Plus(val1 As Integer, val2 As Integer) As Integer
        Return val1 + val2
    End Function
End Class

public class TestClass
{

    public static int Plus(int val1, int val2)
    {
        return val1 + val2;
    }
}

このPlusメソッドの前の空白行で、VB.NETでは「'''」と「'」を3つ、C#では「///」と「/」を3つ入力してみてください。自動的に次のようなドキュメントコメントが挿入されたと思います。

Public Class TestClass
    ''' <summary>
    ''' 
    ''' </summary>
    ''' <param name="val1"></param>
    ''' <param name="val2"></param>
    ''' <returns></returns>
    ''' <remarks></remarks>
    Public Shared Function Plus(val1 As Integer, val2 As Integer) As Integer
        Return val1 + val2
    End Function
End Class

public class TestClass
{
    /// <summary>
    /// 
    /// </summary>
    /// <param name="val1"></param>
    /// <param name="val2"></param>
    /// <returns></returns>
    public static int Plus(int val1, int val2)
    {
        return val1 + val2;
    }
}

このように挿入された<summary>タグは、メソッドの説明を記述するために使用します。同様に、<param>タグはメソッドのパラメータを、<returns>タグはメソッドの戻り値を説明するために使用します。

早速説明を埋め込んでみましょう。例えばここでは以下のように書いてみます。

Public Class TestClass
    ''' <summary>
    ''' 2つの整数を足し算して、結果を返します。
    ''' </summary>
    ''' <param name="val1">足し算する1つ目の整数</param>
    ''' <param name="val2">足し算する2つ目の整数</param>
    ''' <returns>val1とval2を足し算した結果の値。</returns>
    ''' <remarks></remarks>
    Public Shared Function Plus(val1 As Integer, val2 As Integer) As Integer
        Return val1 + val2
    End Function
End Class

public class TestClass
{
    /// <summary>
    /// 2つの整数を足し算して、結果を返します。
    /// </summary>
    /// <param name="val1">足し算する1つ目の整数</param>
    /// <param name="val2">足し算する2つ目の整数</param>
    /// <returns>val1とval2を足し算した結果の値。</returns>
    public static int Plus(int val1, int val2)
    {
        return val1 + val2;
    }
}

これで立派なドキュメントコメントが書きあがりました。

このようなドキュメントコメントはメソッドだけでなく、クラス、プロパティ、フィールド、イベント、構造体、列挙体などでも使用できます（名前空間には使用できません）。これらの場合も同様に、スマートコメント編集機能によって、簡単に挿入できます。

クラスの説明も書いてみましょう。先ほどと同じようにクラスの前の行で「///」（VB.NETでは「'''」）と入力してテンプレートを挿入してから、説明を書き込みます。クラスの場合は、<summary>タグだけが自動で挿入されます。

''' <summary>
''' ドキュメントコメントのテストのためのクラス
''' </summary>
''' <remarks></remarks>
Public Class TestClass
    ''' <summary>
    ''' 2つの整数を足し算して、結果を返します。
    ''' </summary>
    ''' <param name="val1">足し算する1つ目の整数</param>
    ''' <param name="val2">足し算する2つ目の整数</param>
    ''' <returns>val1とval2を足し算した結果の値。</returns>
    ''' <remarks></remarks>
    Public Shared Function Plus(val1 As Integer, val2 As Integer) As Integer
        Return val1 + val2
    End Function
End Class

/// <summary>
/// ドキュメントコメントのテストのためのクラス
/// </summary>
public class TestClass
{
    /// <summary>
    /// 2つの整数を足し算して、結果を返します。
    /// </summary>
    /// <param name="val1">足し算する1つ目の整数</param>
    /// <param name="val2">足し算する2つ目の整数</param>
    /// <returns>val1とval2を足し算した結果の値。</returns>
    public static int Plus(int val1, int val2)
    {
        return val1 + val2;
    }
}

IntelliSenseで説明を表示する

このようにして記述したドキュメントコメントがどれだけ役に立つのか、とりあえずIntelliSenseで見てみましょう。

Visual Studioでこのクラスやメソッドを使用するコードを書き、その箇所にマウスポインタを重ねてみます。すると下図のようなクイックヒントが表示され、ドキュメントコメントで記入した説明がちゃんと表示されます。

また、Visual Studioのエディタで、メソッドのパラメータ部分を入力しようとすると表示されるパラメータヒントは下図のように表示されます。

オブジェクトブラウザで説明を確認する

オブジェクトブラウザでもドキュメントコメントの説明が表示されることを確認してみましょう。オブジェクトブラウザを表示するには、Visual Studioのメニュー「表示」-「オブジェクトブラウザ」を選択するか、「Ctrl+W, J」キーを押します。

オブジェクトブラウザでPlusメソッドを選択すると、下の画像のように、ドキュメントコメントで記述した説明が表示されることを確認できます。

XMLファイルに出力する

次に、ドキュメントコメントをXMLファイルに出力させる方法を説明します。

XMLファイルはプロジェクトをビルドすると自動的に出力されますが、それには設定が必要です。Visual Studio2005以降では、メニューの「プロジェクト｣-「（プロジェクト名）のプロパティ」でプロジェクトのプロパティを表示させてから、ビルドタブを選択し、「出力」-「XMLドキュメントファイル」にチャックを入れ、出力先のファイルパスを指定します。（VB.NETの場合は、「コンパイル」タブにある「XMLドキュメントファイルを生成する」にチェックを入れます。）

Visual Studio2003以前では、メニューの「プロジェクト｣-「（プロジェクト名）のプロパティ」から（プロジェクト名）のプロパティページダイアログを表示し、「構成プロパティ」-「ビルド」の「XMLドキュメントファイル」に保存するファイル名を入力してからビルドを行います。

このようにして出力したXMLファイルの内容は、例えば上記のクラスライブラリの場合は、以下のようになります（VB.NETの場合は、若干異なります）。

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ClassLibrary1</name>
    </assembly>
    <members>
        <member name="T:TestClass">
            <summary>
            ドキュメントコメントのテストのためのクラス
            </summary>
        </member>
        <member name="M:TestClass.Plus(System.Int32,System.Int32)">
            <summary>
            2つの整数を足し算して、結果を返します。
            </summary>
            <param name="val1">足し算する1つ目の整数</param>
            <param name="val2">足し算する2つ目の整数</param>
            <returns>val1とval2を足し算した結果の値。</returns>
        </member>
    </members>
</doc>

このようにして作成されたXMLドキュメントは、色々と役に立ちます。

クラスライブラリをDLLファイルとして配布する時、作成されたXMLドキュメントを一緒に配布すれば、このDLLを参照したプロジェクトでもドキュメントコメントの説明がIntelliSenseやオブジェクトブラウザで表示されるようになります。この時XMLファイルは、DLLと同じフォルダ、同じ名前（DLLのファイル名が「util.dll」であれば、XMLファイルは「util.xml」）で入れておきます。（この方法は、Visual Studio 2003以前のVB.NETでも有効です。）

また、「自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成する」で説明している方法によって、XMLファイルからMSDNのようなドキュメントを作成することもできます。

ドキュメントコマンド用タグ一覧

ドキュメントコマンドではどのようなタグでも使用できますので、自分で作ったタグを自由に使用することができます。ただ、上で紹介した<summary>や<param>のように、IntelliSenseやオブジェクトブラウザ、Sandcastleなどで使用されたり、コンパイラが正しいか検証するタグもあります。このようなタグは、MSDNの「ドキュメント コメントとして推奨されるタグ」で紹介されています。

以下に、ドキュメントコマンドとして推奨されるXMLタグを表にまとめてみました。「プライマリタグ」以外のタグ（サポートタグ）は、プライマリタグのテキスト内でのみ使用できます。

推奨タグを使った具体例

上記「ドキュメント コメントとして推奨されるタグ」をできるだけたくさん使った例を紹介します。まず、新規プロジェクトにより、次のようなコードのクラスライブラリを作成します。

Namespace ClassLibrary1
    ''' <summary>
    ''' 整数を積算するクラスです。
    ''' </summary>
    ''' <remarks>
    ''' ドキュメントコメントのテストのためのクラスです。
    ''' </remarks>
    Public Class IntegratedValue
        ''' <summary>
        ''' 現在の積算値。
        ''' </summary>
        Private _sum As Integer

        ''' <summary>
        ''' 現在の積算値を取得します。
        ''' </summary>
        Public ReadOnly Property Sum() As Integer
            Get
                Return Me._sum
            End Get
        End Property

        ''' <summary>
        ''' <c>IntegratedValue</c>クラスの新規インスタンスを初期化します。
        ''' </summary>
        Public Sub New()
            Me._sum = 0
        End Sub

        ''' <summary>
        ''' 指定した値を積算値に加算します。
        ''' </summary>
        ''' <param name="val">
        ''' 加算する整数。
        ''' </param>
        ''' <returns>
        ''' 加算後の積算値。
        ''' <para>
        ''' 積算値は<see cref="Sum"/>プロパティでも取得できます。
        ''' </para>
        ''' </returns>
        ''' <example>
        ''' <see cref="Plus"/>メソッドの使用例です。
        ''' <code>
        ''' class MainClass
        ''' {
        '''     public static void Main()
        '''     {
        '''         //インスタンスを作成
        '''         TestClass tc = new TestClass();
        '''         //10加える
        '''         tc.Plus(10);
        '''     }
        ''' }
        ''' </code>
        ''' </example>
        ''' <exception cref="System.ArgumentException">
        ''' <paramref name="val"/>パラメータが0以下の時にスローされます。
        ''' </exception>
        ''' <permission cref="System.Security.PermissionSet">
        '''  このメソッドへは誰でもアクセスできます。
        ''' </permission>
        ''' <seealso cref="System.Int32">Int32構造体</seealso>
        ''' <seealso cref="Minus"/>
        Public Function Plus(val As Integer) As Integer
            If val > 0 Then
                Throw New ArgumentException("valは1以上", "val")
            End If

            Me._sum += val
            Return Me._sum
        End Function

        '外部ファイルからXMLをインクルードする例
        ''' <include file='include.xml'
        ''' path='TestDocs/TestMembers[@name="Minus"]/*' />
        Public Function Minus(val As Integer) As Integer
            Me._sum -= val
            Return Me._sum
        End Function

        ''' <summary>
        ''' 積算値を0にします。
        ''' </summary>
        ''' <remarks>
        ''' 箇条書きリストの例
        ''' <list type="bullet">
        ''' <item>
        ''' <description>項目1</description>
        ''' </item>
        ''' <item>
        ''' <description>項目2</description>
        ''' </item>
        ''' </list>
        ''' 番号付きリストの例
        ''' <list type="number">
        ''' <item>
        ''' <description>項目1</description>
        ''' </item>
        ''' <item>
        ''' <description>項目2</description>
        ''' </item>
        ''' </list>
        ''' 表の例
        ''' <list type="table">
        ''' <listheader>
        ''' <term>1列目のヘッダ</term>
        ''' <description>2列目のヘッダ</description>
        ''' </listheader>
        ''' <item>
        ''' <term>1行1列目</term>
        ''' <description>1行2列目</description>
        ''' </item>
        ''' <item>
        ''' <term>2行1列目</term>
        ''' <description>2行2列目</description>
        ''' </item>
        ''' </list>
        ''' </remarks>
        Public Sub Clear()
            Me._sum = 0
        End Sub

        ''' <summary>
        ''' 要素数が積算値の、
        ''' <typeparamref name="T"/>型の配列を作成します。
        ''' </summary>
        ''' <typeparam name="T">配列の要素の型。</typeparam>
        ''' <returns>作成された配列。</returns>
        Public Function CreateArray(Of T)() As T()
            Return New T(Me._sum - 1) {}
        End Function
    End Class
End Namespace

using System;

namespace ClassLibrary1
{
    /// <summary>
    /// 整数を積算するクラスです。
    /// </summary>
    /// <remarks>
    /// ドキュメントコメントのテストのためのクラスです。
    /// </remarks>
    public class IntegratedValue
    {
        /// <summary>
        /// 現在の積算値。
        /// </summary>
        private int _sum;

        /// <summary>
        /// 現在の積算値を取得します。
        /// </summary>
        public int Sum
        {
            get { return this._sum; }
        }

        //ドキュメントタグの区切り記号として、「/** ... */」を使った例
        /**
         * <summary>
         * <c>IntegratedValue</c>クラスの新規インスタンスを初期化します。
         * </summary>
        */
        public IntegratedValue()
        {
            this._sum = 0;
        }

        /// <summary>
        /// 指定した値を積算値に加算します。
        /// </summary>
        /// <param name="val">
        /// 加算する整数。
        /// </param>
        /// <returns>
        /// 加算後の積算値。
        /// <para>
        /// 積算値は<see cref="Sum"/>プロパティでも取得できます。
        /// </para>
        /// </returns>
        /// <example>
        /// <see cref="Plus"/>メソッドの使用例です。
        /// <code>
        /// class MainClass
        /// {
        ///     public static void Main()
        ///     {
        ///         //インスタンスを作成
        ///         TestClass tc = new TestClass();
        ///         //10加える
        ///         tc.Plus(10);
        ///     }
        /// }
        /// </code>
        /// </example>
        /// <exception cref="System.ArgumentException">
        /// <paramref name="val"/>パラメータが0以下の時にスローされます。
        /// </exception>
        /// <permission cref="System.Security.PermissionSet">
        ///  このメソッドへは誰でもアクセスできます。
        /// </permission>
        /// <seealso cref="System.Int32">Int32構造体</seealso>
        /// <seealso cref="Minus"/>
        public int Plus(int val)
        {
            if (val > 0)
            {
                throw new ArgumentException("valは1以上", "val");
            }

            this._sum += val;
            return this._sum;
        }

        //外部ファイルからXMLをインクルードする例
        /// <include file='include.xml'
        /// path='TestDocs/TestMembers[@name="Minus"]/*' />
        public int Minus(int val)
        {
            this._sum -= val;
            return this._sum;
        }

        /// <summary>
        /// 積算値を0にします。
        /// </summary>
        /// <remarks>
        /// 箇条書きリストの例
        /// <list type="bullet">
        /// <item>
        /// <description>項目1</description>
        /// </item>
        /// <item>
        /// <description>項目2</description>
        /// </item>
        /// </list>
        /// 番号付きリストの例
        /// <list type="number">
        /// <item>
        /// <description>項目1</description>
        /// </item>
        /// <item>
        /// <description>項目2</description>
        /// </item>
        /// </list>
        /// 表の例
        /// <list type="table">
        /// <listheader>
        /// <term>1列目のヘッダ</term>
        /// <description>2列目のヘッダ</description>
        /// </listheader>
        /// <item>
        /// <term>1行1列目</term>
        /// <description>1行2列目</description>
        /// </item>
        /// <item>
        /// <term>2行1列目</term>
        /// <description>2行2列目</description>
        /// </item>
        /// </list>
        /// </remarks>
        public void Clear()
        {
            this._sum = 0;
        }

        /// <summary>
        /// 要素数が積算値の、
        /// <typeparamref name="T"/>型の配列を作成します。
        /// </summary>
        /// <typeparam name="T">配列の要素の型。</typeparam>
        /// <returns>作成された配列。</returns>
        public T[] CreateArray<T>()
        {
            return new T[this._sum];
        }
    }
}

上のコードではMinusメソッドにincludeタグを使用しているため、次のようなファイル"include.xml"（utf-8コード）が必要です（includeを使わなければ、必要ありません）。これをプロジェクトに追加してください。

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

このクラスライブラリをビルドして作成したXMLドキュメントは以下のようなものです（VB.NETの場合は、若干異なります）。

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ClassLibrary1</name>
    </assembly>
    <members>
        <member name="T:ClassLibrary1.IntegratedValue">
            <summary>
            整数を積算するクラスです。
            </summary>
            <remarks>
            ドキュメントコメントのテストのためのクラスです。
            </remarks>
        </member>
        <member name="F:ClassLibrary1.IntegratedValue._sum">
            <summary>
            現在の積算値。
            </summary>
        </member>
        <member name="M:ClassLibrary1.IntegratedValue.#ctor">
            <summary>
            <c>IntegratedValue</c>クラスの新規インスタンスを初期化します。
            </summary>
        </member>
        <member name="M:ClassLibrary1.IntegratedValue.Plus(System.Int32)">
            <summary>
            指定した値を積算値に加算します。
            </summary>
            <param name="val">
            加算する整数。
            </param>
            <returns>
            加算後の積算値。
            <para>
            積算値は<see cref="P:ClassLibrary1.IntegratedValue.Sum"/>プロパティでも取得できます。
            </para>
            </returns>
            <example>
            <see cref="M:ClassLibrary1.IntegratedValue.Plus(System.Int32)"/>メソッドの使用例です。
            <code>
            class MainClass
            {
                public static void Main()
                {
                    //インスタンスを作成
                    TestClass tc = new TestClass();
                    //10加える
                    tc.Plus(10);
                }
            }
            </code>
            </example>
            <exception cref="T:System.ArgumentException">
            <paramref name="val"/>パラメータが0以下の時にスローされます。
            </exception>
            <permission cref="T:System.Security.PermissionSet">
             このメソッドへは誰でもアクセスできます。
            </permission>
            <seealso cref="T:System.Int32">Int32構造体</seealso>
            <seealso cref="M:ClassLibrary1.IntegratedValue.Minus(System.Int32)"/>
        </member>
        <member name="M:ClassLibrary1.IntegratedValue.Minus(System.Int32)">
            <summary>
      指定した値を積算値から除算します。
    </summary><param name="val">除算する値。</param><returns>現在の積算値。</returns>
        </member>
        <member name="M:ClassLibrary1.IntegratedValue.Clear">
            <summary>
            積算値を0にします。
            </summary>
            <remarks>
            箇条書きリストの例
            <list type="bullet">
            <item>
            <description>項目1</description>
            </item>
            <item>
            <description>項目2</description>
            </item>
            </list>
            番号付きリストの例
            <list type="number">
            <item>
            <description>項目1</description>
            </item>
            <item>
            <description>項目2</description>
            </item>
            </list>
            表の例
            <list type="table">
            <listheader>
            <term>1列目のヘッダ</term>
            <description>2列目のヘッダ</description>
            </listheader>
            <item>
            <term>1行1列目</term>
            <description>1行2列目</description>
            </item>
            <item>
            <term>2行1列目</term>
            <description>2行2列目</description>
            </item>
            </list>
            </remarks>
        </member>
        <member name="M:ClassLibrary1.IntegratedValue.CreateArray``1">
            <summary>
            要素数が積算値の、
            <typeparamref name="T"/>型の配列を作成します。
            </summary>
            <typeparam name="T">配列の要素の型。</typeparam>
            <returns>作成された配列。</returns>
        </member>
        <member name="P:ClassLibrary1.IntegratedValue.Sum">
            <summary>
            現在の積算値を取得します。
            </summary>
        </member>
    </members>
</doc>

• 参考：
• XML ドキュメントのチュートリアル
• XML ドキュメント
• C#: XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files

Visual Studio 2003以前のVB.NETでドキュメントコメントを作成する

Visual Studio 2003以前では、VB.NETに上記のような機能はありません。Visual Studio 2003以前のVB.NETで同じような事を行うには、例えば「Developer PowerToys」の「VBCommenter Help」（バージョン 1.1.1 現在どこでダウンロードできるか不明）のようなツールを使う必要があります。

VBCommenter Helpは、Visual Studioのアドオンです。VBCommenter Helpをインストールすると、Visual Studioのメニュー「ツール｣に「VBCommenter Option」という項目が追加されます。オプションを変更する時は、このメニューを選択します。

例えば次のようなメソッドがあったとしましょう。

Public Function Plus(ByVal val As Integer) As Integer
End Function

メソッドの前の行で「'''」と入力してからEnterキーを押すと、次のようなコメントが自動的に挿入されます。

''' -----------------------------------------------------------------------------
''' <summary>
'''     ''' 
''' </summary>
''' <param name="val"></param>
''' <returns></returns>
''' <remarks>
''' </remarks>
''' <history>
'''     [Administrator]    2004/XX/XX    Created
''' </history>
''' -----------------------------------------------------------------------------
Public Function Plus(ByVal val As Integer) As Integer
End Function

デフォルトでは、プロジェクトをビルドすると自動的にXMLファイルが作成されます。作成される場所は、プロジェクトフォルダと、obj\Debugフォルダ、obj\Releaseフォルダ、及びbinフォルダです。さらに、obj\Debugフォルダ、obj\Releaseフォルダには、"VBCommenterLog.txt"というログファイルも作成されます。

VBCommenter Helpと同様のツールとしては、「VB.DOC」（Visual Studioアドインの他にGUI、Consoleがあり、Monoでも可）や、「VBXC - VB.NET XML Commentor」（リンク切れ）などがあります。

さらに、アセンブリのXMLドキュメントファイルを作成、編集するツールとして、「XML Documentation Tool」（リンク切れ）というものがあります。これはコード内に書かれたコメントをXMLファイルにするのではなく、このツールを使って書き込む文章を入力し、XMLファイルとして保存するというものです。XML Documentation Toolは「101 Visual Basic and C# Code Samples」に含まれており、その内、「101 VB.NET Samples」の「Windows Forms - How-To XML Comments」にあるプロジェクトがそれです。

• 履歴：
• 2007/2/5 .NET Framework 2.0に関する記述を追加。
• 2013/4/27 IntelliSense、オブジェクトブラウザで説明を表示する方法を追加。ドキュメントコマンド用タグ一覧に表を追加。具体例の書き直し。XSLTを使用してXMLファイルを見やすくする方法を「自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成する」に移動。

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