利用できるさまざまな要素
すでに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！
| 更新履歴 |
| 【2002.1.11】記事の最後に謝辞を追加しました。 |
|
Insider.NET 記事ランキング
本日
月間
