連載

C#入門

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

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


利用できるさまざまな要素

 すでにsummary要素とparam要素を紹介したが、ドキュメントを成立させるために必要な他の項目にも要素が定義されている。以下はそれを用いた例である。

 1: using System;
 2:
 3: namespace ConsoleApplication12
 4: {
 5:   /// <summary>
 6:   /// ドキュメントを説明するサンプルクラスです。
 7:   /// </summary>
 8:   class Class1
 9:   {
10:     /// <summary>
11:     /// 整数の足し算を行います。
12:     /// <c>int a = sampleAdd(1,2);</c>とすると、変数aに結果が入ります。
13:     /// </summary>
14:     /// <example>
15:     /// static void Main(string[] args)
16:     /// {
17:     ///   Console.WriteLine( sampleAdd(1,2) );
18:     /// }
19:     /// </example>
20:     /// <param name="value1">足す数その1です。</param>
21:     /// <param name="value2">足す数その2です。</param>
22:     /// <returns>足し算の結果です。</returns>
23:     /// <remarks>もちろん、このメソッドは説明のためのもので、実用性はありません。</remarks>
24:     /// <exception cref="System.OverflowException">int型の最大値を超えた場合です。</exception>
25:     static int sampleAdd( int value1, int value2 )
26:     {
27:       return value1 + value2;
28:     }
29:     /// <value>テストの整数値を持つプロパティです。</value>
30:     int sampleProperty
31:     {
32:       get { return 123; }
33:     }
34:     /// <summary>
35:     /// 最初に実行されるメソッドです。
36:     /// </summary>
37:     /// <param name="args">コマンドライン引数を受け取ります。</param>
38:     static void Main(string[] args)
39:     {
40:       Console.WriteLine("Hello!");
41:     }
42:   }
43: }
さまざまな要素を用いたサンプル・プログラム12
リターン値や発生する例外の説明、コード例などを記述する要素も用意されている。

 まず「c要素」は、コードを記述するために使われる。12行目のように、メソッド名やコードの断片などを文章中に埋め込むために使われる。複数行に渡る場合は「code要素」を使う。「example要素」は、使用例を記述する。「returns要素」はリターン値の説明を記述する。「remarks要素」は補足説明を記述する。「exception要素」は、発生しうる例外の種類と説明を記述する。「cref属性」は、発生する例外のクラス名を記述する。「value要素」は、プロパティの説明を記述する。

 これを前述のスタイル・シートで表示させると以下のようになる。

スタイル・シートを用いた表示例
サンプル・プログラム12から出力されたXMLドキュメントに“doc.xsl”を適用したもの。

■コラム 埋め込みドキュメントから多種のドキュメントを生成するNDoc

 C#の埋め込みドキュメントは、さまざまな可能性を秘めているが、まだその可能性が活用されているとはいい難い。しかし、未来の可能性をかいま見せてくれるソフトがあるので紹介する。SourceForgeで公開されている“NDoc”というソフトがそれだ。実際に試してみたが、日本語が通らなかったり、不明のエラーが出たりするが、未来の可能性を見せてくれるに十分な機能は備えている。

 NDocは、.NETフレームワークのアセンブリから情報を抽出して、JavaDoc形式、MSDN形式(HTML Help形式)、XML形式、XSLT形式(XSLTスタイル・シートで見るXML形式)のドキュメントを生成することができる。GUI操作時のNDocは、以下のようなウィンドウになっている。

NDocの実行時画面
埋め込みドキュメントから多種のドキュメントを生成することができる。

 これに必要な情報を設定した後に、ドキュメントを生成させればよいのである。たとえばMSDN形式なら、HTML Helpのコンパイラを起動して、ファイルを生成してくれる。添付のサンプル・データから生成したものが以下である。

NDocによるMSDN形式の出力例
MSDNライブラリ・リファレンスのような、きれいな出力を得ることができる。

 見てのとおり、MSDNのライブラリを見ているかのような錯覚を感じるものだが、これは正真正銘、C#の埋め込みドキュメントから自動生成したものである。ちなみに、この説明文は、ソースの以下の部分に対応するものである。

/// <summary>Represents an abstract class.</summary>
public abstract class Abstract
{
  /// <summary>This event is decalred in the Abstract class.</summary>
  public abstract event Handler InterfaceEvent;
}

 このような美麗なドキュメントを自動生成するツールは、今後サード・パーティーや有志によって、多種多様な機能を持つものが開発されていくことが予想される。

まとめ

 プリプロセッサは、開発現場ではしばしば必要とされる機能なので、頭の中に入れておく価値がある。実際、プリプロセッサ命令が埋め込まれたソースは珍しいものではない。一方、埋め込みドキュメントの方は、すぐに華々しく活用できるものではない。また、この連載でも、これまでサンプル・ソースにドキュメントを埋め込んでこなかった。しかし、これは埋め込みドキュメントの価値が低いということではない。サンプル・ソースは、読者が把握しやすいようにできるだけコンパクトに書いているので、埋め込みドキュメントは割愛しているだけのことである。分量の多い実用的なソースコードなら、埋め込みドキュメントをきちんと記述することにより、ソース全体を分かりやすく要約した文書を自動生成でき、非常に有用である。逆にいえば、ソースを読む際にそのような文書が欲しくなるようなら、こまめに埋め込みドキュメントを記述すべきといえる。

 さて、次回はC#のアトリビュート(属性)について取り上げたいと考えている。

 それでは次回もLet's See Sharp!End of Article

謝辞:今回の原稿執筆にあたり、C#メーリング・リスト(http://www.users.gr.jp/ml/CS.asp)にて情報を提供していただきました。貴重な情報をありがとうございます。


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

更新履歴
【2002.1.11】記事の最後に謝辞を追加しました。
 
「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 記事ランキング

本日 月間