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

■コンテンツ

■ブックマーク

■Translate

■その他

■広告

DOBON.NET > プログラミング道 > .NET Tips > その他のTips

ドキュメントコメントにより型の概要をXMLファイルに出力する
この記事への評価、コメント、トラックバック

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

C#の場合

C#のコンパイラには、XML形式のドキュメントコメント（コードコメント、XMLスタイルコメント）をソースコードに記述することによって、クラスやメンバなどの型の概要をXMLファイルとして出力する機能があります。またタグによっては、IntelliSense、オブジェクトブラウザ、コードコメントWebレポートにも使用されます。

Visual Studioでは、「スマートコメント編集」と呼ばれる機能により、簡単にドキュメントコメントを挿入することができます（この設定は、メニューの「ツール」-「オプション」で表示されるオプションダイアログの「テキストエディタ」-「C#」-「書式設定」にある「スマートコメント編集」で変更できます）。例えば、

[C#]
public int Plus(int val)
{
}

というメソッドがあったとき、このメソッドの前の空白行で
///
と入力すると、自動的に次のようにドキュメントコメントが挿入されます。

[C#]
/// <summary>
/// 
/// </summary>
/// <param name="val"></param>
/// <returns></returns>
public int Plus(int val)
{
}

ここで<summary>タグはメソッドを説明するために使用し、<param>タグはメソッドのパラメータを、<returns>タグはメソッドの戻り値を説明するために使用します。

これ以外にドキュメントコメントで一般的に使用されるXMLタグはヘルプの「ドキュメントコメントとして推奨されるタグ」で説明されています。

また、ドキュメントタグの区切り記号としては、
///
の他にも、
/** ... */
で囲む方法もあります。（下の例のTestClassコンストラクタで使用しています。）

以下にドキュメントコメントを使用した具体的な例を紹介します（ここでは「ドキュメントコメントとして推奨されるタグ」で紹介されているほぼすべてのタグを使用しています）。まず、新規プロジェクトにより、次のようなコードのクラスライブラリを作成します。

[C#]
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;
        }
    }
}

上のコードでは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ドキュメントを出力するには、Visual Studioの場合、メニューの「プロジェクト｣-「（プロジェクト）のプロパティ」から（プロジェクト）のプロパティページダイアログを表示し、「構成プロパティ」-「ビルド」の「XMLドキュメントファイル」に保存するファイル名を入力してからビルドを行います。（.NET SDKの場合は、/docコンパイラオプションを使用します。）

上のクラスライブラリが生成したXMLドキュメントの内容は次のようになります。

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ClassLibrary1</name>
    </assembly>
    <members>
        <member name="T:ClassLibrary1.TestClass">
            <summary>
            テストのクラスです。
            </summary>
            <exception cref="T:System.Exception">
            ここには例外の説明を書きます。
            </exception>
        </member>
        <member name="F:ClassLibrary1.TestClass._sum">
            <summary>
            現在の合計値を保存するフィールド
            </summary>
        </member>
        <member name="M:ClassLibrary1.TestClass.#ctor(System.Int32)">
            <summary>
            <c>TestClass</c>クラスの新規インスタンスを初期化し、
            指定した数を合計値に設定します。
            </summary>
            <param name="val">初期値</param>
        </member>
        <member name="M:ClassLibrary1.TestClass.#ctor">
                    <summary>
                    TestClassクラスの新規インスタンスを初期化します。
                    </summary>
                    * アスタリスクで始まる行は無視されます。
        </member>
        <member name="M:ClassLibrary1.TestClass.Plus(System.Int32)">
            <summary>
            指定した値を合計値に加算します。
            </summary>
            <param name="val">加算する整数</param>
            <returns>現在の合計値</returns>
            <remarks>
            <c>Plus</c>メソッドの
            <paramref name="val"/>パラメータで加算する整数を指定します。
            <para>合計値は<see cref="P:ClassLibrary1.TestClass.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="T:System.Int32">Int32構造体</seealso>
            <seealso cref="M:ClassLibrary1.TestClass.Minus(System.Int32)"/>
            <permission cref="T:System.Security.PermissionSet">
            このメソッドへは誰でもアクセスできます。</permission>
        </member>
        <member name="M:ClassLibrary1.TestClass.Minus(System.Int32)">
            <summary>
指定した値を合計値から除算する。
</summary><param name="val">除算する値。</param>
<returns>現在の合計値。</returns>
        </member>
        <member name="P:ClassLibrary1.TestClass.Sum">
            <summary>
            現在の合計値を取得設定します。
            </summary>
            <value>現在の合計値</value>
        </member>
    </members>
</doc>

VB.NETの場合

.NET Framework 2.0以降では、VB.NETのコンパイラにも、上記で紹介したC#と同様の機能があります。ドキュメントタグの区切り記号は、C#が「///」であったのに対して、VB.NETでは「'''」（'3つ）です。

.NET Framework 1.1以前では、VB.NETにはこのような機能がありません。.NET Framework 1.1以前においてVB.NETで同じ事を行うには、Developer PowerToysのVBCommenter Help（リンク切れ）のようなツールを使う必要があります（現在のバージョンは1.1.1、現在どこでダウンロードできるか不明）。

VBCommenter HelpはVisual Studioのアドオンのため、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

つまり、
///
の代わりに
'''
を先頭に書いて、C#の時と同様にドキュメントコメントを記述することになります。

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

VBCommenter Helpと同様のアプリケーションにはさらに「VB.DOC」（GUI、Console、Visual Studio Addinあり。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」にあるプロジェクトがそれです。

より見やすく表示する

上記のように作成されたXMLファイルですが、このままでは非常に見づらく、分かりにくいです。このXMLファイルを見やすくするための方法が、MSDNの「Introducing the Visual Studio .NET Lab Series」の「Lab 2: XML Comments」で紹介されています。これは、XSLを使用することにより、XMLの表示方法を変更するという方法です。

「Lab 2: XML Comments」の方法をごく簡単に説明します（詳しくはリンク先をご覧ください）。まず適当なXSLファイルを用意し（ここではLab 2: XML Commentsで紹介されている"doc.xsl"をそのまま使われていただきます）、このXSLファイルをXMLファイルと同じフォルダに置き、XMLファイルの先頭の
<?xml version="1.0"?>
と
<doc>
の間に
<?xml-stylesheet href="doc.xsl" type="text/xsl"?>
を書き足して、おしまいです。こうしてできたXMLファイル("doc.xml")をこちらに置いておきますので、どのように表示されるか、確認してみてください。

さらにツールを使って見やすいHTMLファイルを生成する方法を次の「コードコメントWebレポートを作成する」で紹介しています。

履歴：
2007/2/5 .NET Framework 2.0に関する記述を追加。

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

この記事への評価

この記事の評価はこちらでご覧いただけます。各Tipsの評価一覧はこちらです。

この記事へのコメント

この記事へのコメントの一覧はこちらでご覧いただけます。

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

この記事へのトラックバック

この記事へのトラックバックの一覧はこちらでご覧いただけます。

この記事のトラックバック Ping URL (注意事項) :
http://dobon.net/cgi-bin/pc/tb.php/programing/xmldocument.html