XMLドキュメントの埋め込み
さて、ここからは、プリプロセッサではなく、XMLドキュメントの話題である。C#では、ソースコードのコメント内にXML形式で説明を埋め込むことによって、XML形式のドキュメント・ファイルを自動生成する機能がある。以下は、その形式でドキュメントを埋め込んだソースの例である。
1: using System;
2:
3: namespace ConsoleApplication11
4: {
5: /// <summary>
6: /// ドキュメントを説明するサンプルクラスです。
7: /// </summary>
8: class Class1
9: {
10: /// <summary>
11: /// 最初に実行されるメソッドです。
12: /// </summary>
13: /// <param name="args">コマンドライン引数を受け取ります。</param>
14: static void Main(string[] args)
15: {
16: Console.WriteLine("Hello!");
17: }
18: }
19: } |
|
| 埋め込みドキュメントを使用したサンプル・プログラム11 |
| 埋め込みドキュメントは説明したいクラスやメソッドの直前で、「///」に続いて記述する。 |
通常のコメントは「//」に続けて書くが、埋め込みドキュメントは「///」と3文字のスラッシュに続いて記述する。埋め込みドキュメントは、説明したいクラスやメソッドの直前に書く。つまり、5〜7行目のドキュメントは、8行目以降のClass1クラスの説明になっている。「summary要素」には概要を記述する。ここでは、Class1クラスの概要を記述している。また同様に10〜12行目のsummary要素はMainメソッドの概要を記述している。もう1つ、13行目には「param要素」も見えているが、これは引数についての説明を記述する要素である。「name属性」で引数の名前を指定して、要素の内容に説明文を記述する。
さて、埋め込みドキュメントを書くだけでは何も起きない。XML形式のファイルを生成するには、以下のようにプロジェクトのプロパティの[XMLドキュメント ファイル]でファイル名を指定しなければならない。
 |
| [プロパティページ]ダイアログ |
| [XMLドキュメント ファイル]でドキュメント（XML形式）のファイル名を指定する。
|
この指定を付けてビルドすると、指定したファイル名でXMLファイルが生成される。これをInternet Explorer 5.0以降で開くと以下のように見える。
 |
| 生成されたXMLドキュメントをIEで開いた画面 |
| ソースコードに記述したクラスとメソッドの解説が含まれているのが分かる。
|
こんなものを作って何が面白いのだと思われるかもしれないが、これはドキュメントそのものというよりも、ドキュメントの種である。必要に応じてこの種を使い、読みやすい形式に変換することが可能である。
ドキュメントを読む方法
最も簡単に生成したドキュメントを読む方法は、Microsoftが提供するXSLTスタイル・シートを用いる方法である。これは少々分かりにくい手順なので詳しく説明しよう。まず、Microsoftのサイトにある「Lab
2: XML Comments」というページから、“ExpVSNET.exe”を入手する。このファイルは自己解凍ファイルなので、実行して内容を自分のハード・ディスクに格納する。その中に“HOLT1-01
Experience Visual Studio.NET.msi”というWindowsインストーラー形式のファイルがあるので、これをインストールする。インストールしたディレクトリ内に“DemoFilesAndDocs\FieldContent\Experience
VS.NET\Lab2”というディレクトリがあるので、その中を見る。そこに“doc.xsl”というファイルがあるので、これを自分で生成したXMLファイルのあるディレクトリにコピーしてくる。そして、XMLファイルの1行目の後ろに、以下の1行を挿入する。
<?xml:stylesheet href="doc.xsl" type="text/xsl"?> |
挿入の結果、以下のようになっていればよい。
1: <?xml version="1.0"?>
2: <?xml:stylesheet href="doc.xsl" type="text/xsl"?>
3: <doc>
4: <assembly>
5: <name>ConsoleApplication11</name>
6: </assembly>
7: <members>
8: <member name="T:ConsoleApplication11.Class1">
9: <summary>
10: ドキュメントを説明するサンプルクラスです。
11: </summary>
12: </member>
13: <member name="M:ConsoleApplication11.Class1.Main(System.String[])">
14: <summary>
15: 最初に実行されるメソッドです。
16: </summary>
17: <param name="args">コマンドライン引数を受け取ります。</param>
18: </member>
19: </members>
20: </doc> |
|
| スタイル・シートを指定したXMLドキュメント |
| 生成されたドキュメント・ファイルを開き、2行目にスタイル・シートを指定した行を追加する。 |
そして、Internet Explorer 5.0以降でこのXML文書を開くと、以下のように書式化されて表示される。こんな地味な文書ができても面白くない、と思われるかもしれないが、これは最低限の方法であって、全てではない。コラム記事も参照して頂きたい。
 |
| 書式化されたXMLドキュメント |
| スタイル・シートを指定することによって、書式化されたものを表示することができる。
|
Insider.NET 記事ランキング
本日
月間
