DOBON.NET プログラミング道: .NET Framework, VB.NET, C#, Visual Basic, Visual Studio, インストーラ, ...

ドキュメントコメントにより型の概要を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以前で使用する方法は、後述します。)

補足:C#では、この機能の有効、無効を切り替えることができます。Visual Studio 2005以降では、メニューの「ツール」-「オプション」で表示されるオプションダイアログから「テキストエディター」-「C#」-「詳細」にある「XMLドキュメントのコメント」-「///に対するXMLドキュメントを生成する」で変更できます。Visual Studio2003以前では、メニューの「ツール」-「オプション」で表示されるオプションダイアログの「テキストエディタ」-「C#」-「書式設定」にある「スマートコメント編集」で変更できます。

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

VB.NET
コードを隠すコードを選択
Public Class TestClass

    Public Shared Function Plus(val1 As Integer, val2 As Integer) As Integer
        Return val1 + val2
    End Function
End Class
C#
コードを隠すコードを選択
public class TestClass
{

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

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

VB.NET
コードを隠すコードを選択
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
C#
コードを隠すコードを選択
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>タグはメソッドの戻り値を説明するために使用します。

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

VB.NET
コードを隠すコードを選択
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
C#
コードを隠すコードを選択
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>タグだけが自動で挿入されます。

VB.NET
コードを隠すコードを選択
''' <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
C#
コードを隠すコードを選択
/// <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;
    }
}
補足:C#ではドキュメントタグの区切り記号としては、「///」の他に、「/** ... */」で囲む方法もあります。詳しくは、「ドキュメント タグの区切り記号」をご覧下さい。

IntelliSenseで説明を表示する

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

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

クイックヒント

補足:クイックヒントは、Ctrl+Kキーを押してからIキーを押すことによっても表示できます。また、メニューの「編集」-「IntelliSense」-「クイックヒント」でも表示できます。

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

パラメータヒント

補足:パラメータヒントは、Ctrl+Kキーを押してからPキーを押すことによっても表示できます。また、メニューの「編集」-「IntelliSense」-「パラメータヒント」でも表示できます。
補足:パラメータヒントは表示しないようにもできます。パラメータヒントを表示しないようにするには、メニューの「ツール」-「オプション」でオプションダイアログを表示し、「テキストエディター」-「C#」(VB.NETでは、「Basic」)-「全般」の「入力候補」-「パラメータヒント」のチェックを外します。

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

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

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

オブジェクトブラウザ

XMLファイルに出力する

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

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

XMLドキュメントファイルを出力する設定

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

補足:.NET SDKでは、/docコンパイラオプションを使用します。

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

このようにして作成された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タグを表にまとめてみました。「プライマリタグ」以外のタグ(サポートタグ)は、プライマリタグのテキスト内でのみ使用できます。

タグ 説明 プライマリタグ
c 説明内のテキストをコードとして記述する。 ×
code 複数行をコードとして記述する。 ×
example メソッドなど使用例を記述する。通常はこのタグ内で<code>も使用する。
exception メソッド、プロパティ、イベント、インデクサーで、スローできる例外と、その例外がどのような時にスローされるかを記述する。スローできる例外は、cref属性に指定する。
コンパイラが構文を検証する。
include 型やメンバの説明として、外部ファイルのXMLドキュメントを参照する。これを使うと、ドキュメントコメントを外部ファイルに記述することができる。XMLのXPath構文を使用する。file属性にファイル名、path属性にXPath式を指定する。
コンパイラが構文を検証する。
list 表または定義リストの見出し行を定義する。表を定義する場合は、見出しには用語のエントリだけを指定する。 ×
para テキストを段落に分ける。 ×
param メソッドのパラメータを説明する。パラメータ名は、name属性に指定する。
コンパイラが構文を検証する。
IntelliSense、オブジェクトブラウザに表示される。
paramref パラメータの参照として指定する。パラメータ名は、name属性に指定する。 ×
permission メンバーへのアクセスについて説明する。cref属性には現在のコンパイル環境からの呼び出しに利用できるメンバーまたはフィールドへの参照を指定できるが、通常は「System.Security.PermissionSet」を指定する。
コンパイラが構文を検証する。
remarks <summary>で指定された型の説明を補足する。
オブジェクトブラウザに表示される。
returns メソッドの戻り値を説明する。
see リンクを指定する。リンク先のメンバや型は、cref属性に指定する。参照セクションに配置するには、<seealso>を使用する。
コンパイラが構文を検証する。
×
seealso 「参照」セクションに表示するエントリを指定する。参照するメンバや型は、cref属性に指定する。テキスト内でリンクを指定するには、<see>を使用する。
コンパイラが構文を検証する。
summary 型や型のメンバーを説明する。型の説明に補足情報を追加するには、<remarks>を使用する。
IntelliSense、オブジェクトブラウザに表示される。
typeparam ジェネリック型またはジェネリックメソッドを宣言して型パラメーターを説明する。
コンパイラが構文を検証する。
IntelliSense、オブジェクトブラウザに表示される。
Visual Studio 2005以降。
typeparamref 型パラメーターの参照として指定する。型パラメーター名は、name属性に指定する。
Visual Studio 2005以降。
×
value プロパティが表す値を説明する。
補足:「B.2 推奨されるタグ」では、<summary>が「型のメンバについて説明します」で、<remarks>が「型について説明します」となっています。しかし「ドキュメント コメント用の推奨タグ」では、<summary>が「型または型のメンバーの説明に使用します」で、<remarks>が「型の情報を追加」となっています。この違いは、Visual Studio 2003の時とそれより後ではこれらのタグの推奨される使い方が変わったからと考えられます。

推奨タグを使った具体例

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

VB.NET
コードを隠すコードを選択
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
C#
コードを隠すコードを選択
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ドキュメントは以下のようなものです(VB.NETの場合は、若干異なります)。

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」という項目が追加されます。オプションを変更する時は、このメニューを選択します。

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

VB.NET
コードを隠すコードを選択

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

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

VB.NET
コードを隠すコードを選択
''' -----------------------------------------------------------------------------
''' <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」にあるプロジェクトがそれです。

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

  • .NET Tipsをご利用いただく際は、注意事項をお守りください。