.NETプログラミング研究 第36号 †

▲ ▼

.NET Tips †

▲ ▼

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

注意

この記事の最新版は「ドキュメントコメントにより型の概要をXMLファイルに出力する」で公開しています。

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

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

  1
  2
  3

public int Plus(int val)
{
}

というメソッドがあったとき、このメソッドの前の空白行で

///

と入力すると、自動的に次のようにドキュメントコメントが挿入されます。

  1
  2
  3
  4
  5
  6
  7
  8

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

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

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

また、ドキュメントタグの区切り記号としては、

///

の他にも、

/** ... */

で囲む方法もあります。（下の例のTestClassコンストラクタで使用しています。）

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

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90

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を使わなければ、必要ありません。）

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10

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

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

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

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75

<?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>

参考：

C#では以上のような機能をコンパイラが提供していますが、VB.NETのコンパイラにはこのような機能がありません（.NET Framework1.1現在。将来的には対応するでしょう）。VB.NETで同じ事を行うには、Developer PowerToysのVBCommenter Helpのようなツールを使う必要があります（記事を書いている時点でのバージョンは1.1.1）。

VBCommenter HelpはVisual Studio .NETのアドオンのため、Visual Studio .NETで使用します。VBCommenter Helpをインストールすると、Visual Studio .NETのメニュー「ツール｣に「VBCommenter Option」という項目が追加されます（このメニューにより、オプションを変更できます）。

デフォルトでは、例えば次のようなメソッドがあったとき、

  1
  2

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

この前の行で

'''

と入力してからEnterキーを押すと、 次のようなコメントが自動的に挿入されます。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14

''' -----------------------------------------------------------------------------
''' <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 .NET 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")を次のURLに置いておきますので、どのように表示されるか、確認してみてください。

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

▲ ▼

コードコメントWebレポートを作成する / ドキュメントコメントが記述されたクラスライブラリのヘルプを作成する †

注意

この記事の最新版は「自作したクラスライブラリのヘルプ（ドキュメント）を作成する」で公開しています。

「コードコメントWebレポート」とは、プロジェクトで定義されているオブジェクト、インターフェイス、メンバ等の構造やコメントなどの情報を.htmファイルとして作成し、表示するためのVisual Studio .NETの機能です。

コードコメントWebレポートは、先に紹介したドキュメントコメントのタグの一部を認識します（VS.NET2003では、C#の場合のみ）。認識するタグは、<summary>、<remarks>、<param>、<returns>、<newpara>（コメント内で新しい段落を開始します）です。

論より証拠、実際どのようなレポートが出力されるのか、見てみましょう。

先ほどと同じクラスライブラリを作成し、このコードコメントWebレポートを作成してみます。まず、Visual Studio .NETのメニュー「ツール｣-「Webページのビルドコメント」で「Webページのビルドコメントダイアログ」を表示します。ここでリポートを作成する場所（デフォルトではプロジェクトフォルダの下のCodeCommentReportフォルダ）等を指定し、「OK」をクリックすると、出来上がりです。

このようにして実際に作成されたコードコメントWebレポートは、次のURLのようになります。（正しく表示されませんが、これは作成されたHTMLのリンク先と、実際のファイル名が、大文字、小文字で異なり、正しくリンクされないためです。）

参考：

コードコメントWebレポートと同様のツールに、「NDoc」があります。NDocはHTMLだけでなく、HTML Helpファイル（.chm）も作成することができ、さらにVisual Studio .NET Helpフォーマット（HTML Help 2）など、様々なフォーマットにも対応しています。出力されるHTMLファイルは見慣れたMSDNスタイルなので、非常に分かりやすく、見やすいです。

NDocは先に紹介したXMLドキュメントが必要になりますので、NDocを使用する前に作成しておきます（アセンブリファイルも必要ですので、ビルドしておく必要もあります）。Visual Studio .NETの場合は、プロジェクトの設定の「XMLドキュメントファイル」にファイル名が指定されていれば、そのソリューションファイルをNDocの「New from Visual Studio Solution」で開くことにより、自動的にアセンブリファイルとXMLドキュメントファイルのパスが読み込まれ、「Select Assemblies to Document」のリストに追加されます。（Addボタンを押してアセンブリファイルとXMLドキュメントファイルのパスを指定することもできます。）後は「Build Documentation」をクリックするだけで、HTMLファイルとHTML Helpファイルがプロジェクトフォルダの下のdocフォルダ内に作られます（デフォルトの設定の場合）。

NDoc Ver 1.3-beta1aと日本語版 Ver 0.1のデフォルトの設定で作成したHTMLファイルを次のURLに置いておきます。

さらに、ヘルプファイルの作成は、「Developer PowerToys」の「Custom Help Builder」でもできるようです。

▲ ▼

IntelliSenseで自作クラスのメンバの説明を表示する †

注意

この記事の最新版は「IntelliSenseで自作クラスのメンバの説明を表示する」で公開しています。

Visual Studio .NETの機能であるIntelliSenseのクイックヒントや、メンバの一覧、パラメータヒントなどで、自作クラスやそのメンバ、パラメータの説明を表示するために、ソースコード内にXMLドキュメントコメントを記述することができます。（この方法はVS.NET2003の時点で、C#のみに対応しています。）「ドキュメントコメントとして推奨されているタグ」のうち、IntelliSenseで表示されるものは、<summary>（説明）と<param>（パラメータの説明）です。ヘルプによると、このうち<summary>タグのテキストは、IntelliSenseの型に関する唯一の情報源とのことです。

また、クラスライブラリなどのアセンブリを参照して使用するときは、先に紹介したXMLドキュメントをアセンブリと同じファイル名で、アセンブリと同じフォルダに置くことにより（つまり、例えば"ClassLibrary1.dll"という名前のアセンブリの場合、"ClassLibrary1.xml"という名前のXMLファイルを用意する）、IntelliSenseで使用されるようになります。（この方法は、VB.NETでも使用できます。）

▲ ▼

コンピュータ雑学 †

ここでは、話すと人に嫌われるなまぬるいコンピュータに関する雑学を紹介します。

▲ ▼

「C++」の「++」の意味は？ †

C++言語は、1983〜1985年にAT&Tベル研究所のストラウストラップ（Bjarne Stroustrup）により開発されました。当初は、Cのコードを出力するプリプロセッサとして開発されました。C++はCを拡張し、CにSimulaのクラスやオブジェクト指向の機能を取り入れた言語で、1983年までは「C with Classes」（クラスつきのC）と呼ばれていました。1983年に「C++」という名前を使うようになりましたが、この「++」はインクリメンタル演算子（変数の値を1つ増加させる演算子）を意味しています。

ちなみに、「C#」の「#」は「C++」のインクリメンタル演算子を2個縦につなげたものであるとか、「++」をずらしたものであるとか言われています。（正確な由来はわかりません。）もし「#」がインクリメンタル演算子を2回続けたものならば、C#で「#」という演算子があり、変数の値が2つ増えるようなことがあれば面白いなと思い、次のようなコードを書いてみました。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12

using System;
 
class MainClass
{
    public static void Main()
    {
        int C = 0;
        C++;
        C#;
        Console.WriteLine(C);
    }
}

しかし残念ながら（当たり前ですが）、コンパイルエラーがでました。「#」はインクリメンタル演算子を2個繋げたものという説は間違っているのかも？！

▲ ▼

コメント †


▲ ▼
ページ情報
  • カテゴリ : .NET
  • 作成日 : 2004-06-28 (月) 06:00:00
  • 作成者 : DOBON!
  • 最終編集日 : 2010-03-21 (日) 02:24:42
  • 最終編集者 : DOBON!
[ トップ ]   [ 編集 | 凍結 | 差分 | バックアップ | 添付 | 複製 | 名前変更 | リロード ]   [ 新規 | 子ページ作成 | 一覧 | 単語検索 | 最終更新 | ヘルプ ]