┏第36号━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ .NETプログラミング研究 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
──＜メニュー＞───────────────────────
■.NET Tips
・ドキュメントコメントにより型の概要をXMLファイルに出力する
・コードコメントWebレポートを作成する
ドキュメントコメントが記述されたクラスライブラリのヘルプを作
成する
・IntelliSenseで自作クラスのメンバの説明を表示する
■コンピュータ雑学
・「C++」の「++」の意味は？
───────────────────────────────
───────────────────────────────
■.NET Tips
───────────────────────────────
●ドキュメントコメントにより型の概要をXMLファイルに出力する
C#のコンパイラには、XML形式のドキュメントコメント（コードコメン
ト、XMLスタイルコメント）をソースコードに記述することによって、
クラスやメンバなどの型の概要をXMLファイルとして出力する機能があ
ります。またタグによっては、IntelliSense、オブジェクトブラウザ、
コードコメントWebレポートにも使用されます。
Visual Studio .NETでは、「スマートコメント編集」と呼ばれる機能
により、簡単にドキュメントコメントを挿入することができます（こ
の設定は、メニューの「ツール」-「オプション」で表示されるオプシ
ョンダイアログの「テキストエディタ」-「C#」-「書式設定」にある
「スマートコメント編集」で変更できます）。例えば、
‥‥▽C# ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
public int Plus(int val)
{
}
‥‥△C# ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
というメソッドがあったとき、このメソッドの前の空白行で
///
と入力すると、自動的に次のようにドキュメントコメントが挿入され
ます。
‥‥▽C# ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
///
///
///
///
///
public int Plus(int val)
{
}
‥‥△C# ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
ここでタグはメソッドを説明するために使用し、タ
グはメソッドのパラメータを、タグはメソッドの戻り値を説
明するために使用します。
これ以外にドキュメントコメントで一般的に使用されるXMLタグはヘル
プの「ドキュメント コメントとして推奨されるタグ」で説明されてい
ます。
[URL]ドキュメント コメントとして推奨されるタグ
http://www.microsoft.com/japan/msdn/library/ja/csref/html/vclrftagsfordocumentationcomments.asp
また、ドキュメントタグの区切り記号としては、
///
の他にも、
/** ... */
で囲む方法もあります。（下の例のTestClassコンストラクタで使用し
ています。）
以下にドキュメントコメントを使用した具体的な例を紹介します（こ
こでは「ドキュメント コメントとして推奨されるタグ」で紹介されて
いるほぼすべてのタグを使用しています）。まず、新規プロジェクト
により、次のようなコードのクラスライブラリを作成します。
‥‥▽C# ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
using System;
namespace ClassLibrary1
{
///
/// テストのクラスです。
///
///
/// ここには例外の説明を書きます。
///
public class TestClass
{
///
/// 現在の合計値を保存するフィールド
///
private int _sum;
///
/// 現在の合計値を取得設定します。
///
/// 現在の合計値
public int Sum
{
get {return _sum;}
set {_sum = value;}
}
///
/// TestClassクラスの新規インスタンスを初期化し、
/// 指定した数を合計値に設定します。
///
/// 初期値
public TestClass(int val)
{
_sum = val;
}
/**
TestClassクラスの新規インスタンスを初期化します。
* アスタリスクで始まる行は無視されます。
*/
public TestClass()
{
_sum = 0;
}
///
/// 指定した値を合計値に加算します。
///
/// 加算する整数
/// 現在の合計値
///
/// Plusメソッドの
/// パラメータで加算する整数を指定します。
/// 合計値はで
/// 取得できます。
///
/// Plusメソッドの使用コード例です。
///
/// class MainClass
/// {
/// public static void Main()
/// {
/// TestNP.TestClass tc = new TestNP.TestClass(100);
/// tc.Plus(10);
/// }
/// }
///
///
/// Int32構造体
///
///
/// このメソッドへは誰でもアクセスできます。
public int Plus(int val)
{
_sum += val;
return _sum;
}
///
public int Minus(int val)
{
_sum -= val;
return _sum;
}
}
}
‥‥△C# ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
上のコードではMinusメソッドにincludeタグを使用しているため、次
のようなファイル"include.xml"（utf-8コード）が必要です。（
includeを使わなければ、必要ありません。）
‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
指定した値を合計値から除算する。
除算する値。
現在の合計値。
‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
XMLドキュメントを出力するには、Visual Studio .NETの場合、メニュー
の「プロジェクト｣-「（プロジェクト）のプロパティ」から（プロジ
ェクト）のプロパティページダイアログを表示し、「構成プロパティ」
-「ビルド」の「XMLドキュメントファイル」に保存するファイル名を
入力してからビルドを行います。（.NET SDKの場合は、/docコンパイ
ラオプションを使用します。）
上のクラスライブラリが生成したXMLドキュメントの内容は次のように
なります。
‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
ClassLibrary1
テストのクラスです。
ここには例外の説明を書きます。
現在の合計値を保存するフィールド
TestClassクラスの新規インスタンスを初期化し、
指定した数を合計値に設定します。
初期値
TestClassクラスの新規インスタンスを初期化します。
* アスタリスクで始まる行は無視されます。
指定した値を合計値に加算します。
加算する整数
現在の合計値
Plusメソッドの
パラメータで加算する整数を指定します。
合計値はで
取得できます。
Plusメソッドの使用コード例です。
class MainClass
{
public static void Main()
{
TestNP.TestClass tc = new TestNP.TestClass(100);
tc.Plus(10);
}
}
Int32構造体
このメソッドへは誰でもアクセスできます。
指定した値を合計値から除算する。
除算する値。
現在の合計値。
現在の合計値を取得設定します。
現在の合計値
‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
参考：
[URL]XML ドキュメントのチュートリアル
http://www.microsoft.com/japan/msdn/library/ja/csref/html/vcwlkxmldocumentationtutorial.asp
[URL]XML ドキュメント
http://www.microsoft.com/japan/msdn/library/ja/csref/html/vcorixmldocumentation.asp
C#では以上のような機能をコンパイラが提供していますが、VB.NETの
コンパイラにはこのような機能がありません（.NET Framework1.1現在。
将来的には対応するでしょう）。VB.NETで同じ事を行うには、
Developer PowerToysのVBCommenter Helpのようなツールを使う必要が
あります（記事を書いている時点でのバージョンは1.1.1）。
[URL]Developer PowerToys
http://www.gotdotnet.com/team/ide/
[URL]VBCommenter Help
http://www.gotdotnet.com/team/ide/helpfiles/VBCommenter.aspx
[URL]VBCommenter Help ダウンロード
http://www.gotdotnet.com/community/workspaces/viewuploads.aspx?id=112b5449-f702-46e2-87fa-86bdf39a17dd
VBCommenter HelpはVisual Studio .NETのアドオンのため、Visual
Studio .NETで使用します。VBCommenter Helpをインストールすると、
Visual Studio .NETのメニュー「ツール｣に「VBCommenter Option」と
いう項目が追加されます（このメニューにより、オプションを変更で
きます）。
デフォルトでは、例えば次のようなメソッドがあったとき、
‥‥▽VB.NET ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
Public Function Plus(ByVal val As Integer) As Integer
End Function
‥‥△VB.NET ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
この前の行で
'''
と入力してからEnterキーを押すと、 次のようなコメントが自動的に
挿入されます。
‥‥▽VB.NET ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
''' -----------------------------------------------------------------------------
'''
''' '''
'''
'''
'''
'''
'''
'''
''' [Administrator] 2004/XX/XX Created
'''
''' -----------------------------------------------------------------------------
Public Function Plus(ByVal val As Integer) As Integer
End Function
‥‥△VB.NET ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
つまり、
///
の代わりに
'''
を先頭に書いて、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」（現在ベータ版。将来商用有料にな
りそう。）などがあります。
[URL]VB.DOC
http://vb-doc.sourceforge.net/
[URL]VBXC - VB.NET XML Commentor
http://vbxmldoc.tor-erik.net/index.shtml
さらに、アセンブリの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」にあるプロジ
ェクトがそれです。
[URL]XML Documentation Tool
http://www.gotdotnet.com/team/vb/
[URL]101 Visual Basic and C# Code Samples
http://www.microsoft.com/downloads/details.aspx?FamilyId=08E3D5F8-033D-420B-A3B1-3074505C03F3&displaylang=en
上記のように作成されたXMLファイルですが、このままでは非常に見づ
らく、分かりにくいです。このXMLファイルを見やすくするための方法
が、MSDNの「Introducing the Visual Studio .NET Lab Series」の「
Lab 2: XML Comments」で紹介されています。これは、XSLを使用する
ことにより、XMLの表示方法を変更するという方法です。
[URL]Introducing the Visual Studio .NET Lab Series
http://msdn.microsoft.com/library/en-us/dv_vstechart/html/vstchexpvsnetintro.asp
[URL]Lab 2: XML Comments
http://msdn.microsoft.com/library/en-us/dv_vstechart/html/vstchexpvsnetlab2.asp
「Lab 2: XML Comments」の方法をごく簡単に説明します（詳しくはリ
ンク先をご覧ください）。まず適当なXSLファイルを用意し（ここでは
Lab 2: XML Commentsで紹介されている"doc.xsl"をそのまま使われて
いただきます）、このXSLファイルをXMLファイルと同じフォルダに置
き、XMLファイルの先頭の
と
の間に
を書き足して、おしまいです。こうしてできたXMLファイル("doc.xml
")を次のURLに置いておきますので、どのように表示されるか、確認し
てみてください。
[URL]doc.xsl
http://dobon.net/vb/dotnet/programing/xmldocument/doc.xsl
[URL]doc.xml
http://dobon.net/vb/dotnet/programing/xmldocument/doc.xml
さらにツールを使って見やすいHTMLファイルを生成する方法を次の「コー
ドコメントWebレポートを作成する」で紹介します。
───────────────────────────────
●コードコメントWebレポートを作成する
ドキュメントコメントが記述されたクラスライブラリのヘルプを作
成する
「コードコメントWebレポート」とは、プロジェクトで定義されている
オブジェクト、インターフェイス、メンバ等の構造やコメントなどの
情報を.htmファイルとして作成し、表示するためのVisual Studio
.NETの機能です。
コードコメントWebレポートは、先に紹介したドキュメントコメントの
タグの一部を認識します（VS.NET2003では、C#の場合のみ）。認識す
るタグは、、、、、（コ
メント内で新しい段落を開始します）です。
論より証拠、実際どのようなレポートが出力されるのか、見てみまし
ょう。
先ほどと同じクラスライブラリを作成し、このコードコメントWebレポー
トを作成してみます。まず、Visual Studio .NETのメニュー「ツール｣
-「Webページのビルドコメント」で「Webページのビルドコメントダイ
アログ」を表示します。ここでリポートを作成する場所（デフォルト
ではプロジェクトフォルダの下のCodeCommentReportフォルダ）等を指
定し、「OK」をクリックすると、出来上がりです。
このようにして実際に作成されたコードコメントWebレポートは、次の
URLのようになります。（正しく表示されませんが、これは作成された
HTMLのリンク先と、実際のファイル名が、大文字、小文字で異なり、
正しくリンクされないためです。）
[URL]ClassLibrary1 の コード コメント Web レポート
http://dobon.net/vb/dotnet/programing/xmldocument/CodeCommentReport/Solution_ClassLibrary1.HTM
参考：
[URL]コード レポートの作成
http://www.microsoft.com/japan/msdn/library/ja/vsintro7/html/vxconCommentingCode.asp
コードコメントWebレポートと同様のツールに、「NDoc」があります。
NDocはHTMLだけでなく、HTML Helpファイル（.chm）も作成することが
でき、さらにVisual Studio .NET Helpフォーマット（HTML Help 2）
など、様々なフォーマットにも対応しています。出力されるHTMLファ
イルは見慣れたMSDNスタイルなので、非常に分かりやすく、見やすい
です。
[URL]NDoc
http://sourceforge.net/projects/ndoc/
[URL]NDoc日本語版
http://sourceforge.jp/projects/ndoc-jp/
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に置いておきます。
[URL]An NDoc Documented Class Library
http://dobon.net/vb/dotnet/programing/xmldocument/doc/index.html
[URL]An NDoc Documented Class Library（日本語版）
http://dobon.net/vb/dotnet/programing/xmldocument/doc-jp/index.html
さらに、ヘルプファイルの作成は、「Developer PowerToys」の「
Custom Help Builder」でもできるようです。
[URL]Developer PowerToys
http://www.gotdotnet.com/team/ide/
[URL]Custom Help Builder
http://www.gotdotnet.com/team/ide/helpfiles/CustomHelpBuilder.aspx
[URL]Custom Help Builder ダウンロード
http://www.gotdotnet.com/Community/Workspaces/viewUploads.aspx?id=c483fdc2-dd38-48ea-9f9e-fb4fd5f86dbf
───────────────────────────────
●IntelliSenseで自作クラスのメンバの説明を表示する
Visual Studio .NETの機能であるIntelliSenseのクイックヒントや、
メンバの一覧、パラメータヒントなどで、自作クラスやそのメンバ、
パラメータの説明を表示するために、ソースコード内にXMLドキュメン
トコメントを記述することができます。（この方法はVS.NET2003の時
点で、C#のみに対応しています。）「ドキュメントコメントとして推
奨されているタグ」のうち、IntelliSenseで表示されるものは、
（説明）と（パラメータの説明）です。ヘルプによ
ると、このうちタグのテキストは、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つ増加させる演算子）を意味し
ています。
[URL]Bjarne Stroustrup's Homepage
http://www.research.att.com/~bs/homepage.html
ちなみに、「C#」の「#」は「C++」のインクリメンタル演算子を2個縦
につなげたものであるとか、「++」をずらしたものであるとか言われ
ています。（正確な由来はわかりません。）もし「#」がインクリメン
タル演算子を2回続けたものならば、C#で「#」という演算子があり、
変数の値が2つ増えるようなことがあれば面白いなと思い、次のような
コードを書いてみました。
‥‥▽C# ここから▽‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
using System;
class MainClass
{
public static void Main()
{
int C = 0;
C++;
C#;
Console.WriteLine(C);
}
}
‥‥△C# ここまで△‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥‥
しかし残念ながら（当たり前ですが）、コンパイルエラーがでました。
「#」はインクリメンタル演算子を2個繋げたものという説は間違って
いるのかも？！
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
■このマガジンの購読、購読中止、バックナンバー、説明に関しては
次のページをご覧ください。
http://www.mag2.com/m/0000104516.htm
■発行人・編集人：どぼん！
(Microsoft MVP for Visual Basic, Oct 2003-Oct 2004)
http://dobon.net
dobon_info@yahoo.co.jp
■ご質問等はメールではなく、掲示板へお願いいたします。
http://dobon.net/vb/bbs.html
■上記メールアドレスへのメールは確実に読まれる保障はありません
（スパム、ウィルス対策です）。メールは下記URLのフォームメール
から送信してください。
http://dobon.net/mail.html
Copyright (c) 2003 - 2004 DOBON! All rights reserved.
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝