連載

C#入門

第19回 プリプロセッサとドキュメント

(株)ピーデー
川俣 晶
2002/01/11


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ドキュメント
スタイル・シートを指定することによって、書式化されたものを表示することができる。
 

 INDEX
  第19回 プリプロセッサとドキュメント
    1.プリプロセッサとは何か
    2.ソースにシンボルの定義を埋め込む
    3.複雑な条件の指定
    4.自作のエラーや警告を発する
  5.XMLドキュメントの埋め込み
    6.利用できるさまざまな要素
 
「C#入門」


Insider.NET フォーラム 新着記事
  • 第2回 簡潔なコーディングのために (2017/7/26)
     ラムダ式で記述できるメンバの増加、throw式、out変数、タプルなど、C# 7には以前よりもコードを簡潔に記述できるような機能が導入されている
  • 第1回 Visual Studio Codeデバッグの基礎知識 (2017/7/21)
     Node.jsプログラムをデバッグしながら、Visual Studio Codeに統合されているデバッグ機能の基本の「キ」をマスターしよう
  • 第1回 明瞭なコーディングのために (2017/7/19)
     C# 7で追加された新機能の中から、「数値リテラル構文の改善」と「ローカル関数」を紹介する。これらは分かりやすいコードを記述するのに使える
  • Presentation Translator (2017/7/18)
     Presentation TranslatorはPowerPoint用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)

注目のテーマ

Insider.NET 記事ランキング

本日 月間