C# Tips
−XMLドキュメントとNDoc−

[トップ] [目次]

XMLドキュメント

C#コンパイラにはXMLでドキュメントを抽出する機能が標準で付いてます（JavaでいうJavaDocと同じようなものです）。 チュートリアル [Web] [ms-help] を見てもらえばだいたいわかるでしょう。
要は

ってだけです。 こちらの「XMLドキュメント」 [Web] [ms-help] も参照してみてください。

雛形

雛形です。とりあえず、これだけ書けば十分かな？ 


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


using System;

namespace Sample {
    
    /// <summary>ここに要約を書く</summary>
    /// <remarks>ここに解説を書く</remarks>
    public interface ISampleInterface {
    }
    
    /// <summary>ここに要約を書く</summary>
    public enum SumpleEnum {
        /// <summary>ここに各メンバの説明を書く</summary>
        NumberOne
    }
    
    /// <summary>ここに要約を書く</summary>
    /// <param name="sender">イベントのソース</param>
    /// <param name="e">イベントデータを格納している<see cref="EventArgs"/>。</param>
    /// <remarks>ここに解説を書く</remarks>
    public delegate void SampleEventHandler(object sender, EventArgs e);
    
    /// <summary>ここに要約を書く</summary>
    /// <remarks>ここに解説を書く</remarks>
    /// <example>
    /// ここに使用例を書く
    /// サンプルコードは以下のように&lt;code&gt;を使う
    /// <code>
    /// class SampleCode {
    ///    ...
    /// }
    /// </code>
    /// </example>
    public class SampleBaseClass {
    }
    
    /// <summary>ここに要約を書く</summary>
    /// <remarks>ここに解説を書く</remarks>
    /// <example>
    /// ここに使用例を書く
    /// サンプルコードは以下のように&lt;code&gt;を使う
    /// <code>
    /// class SampleCode {
    ///    ...
    /// }
    /// </code>
    /// </example>
    public class SampleDeriveClass : SampleBaseClass, ISampleInterface {
        
        /// <summary>ここに要約を書く</summary>
        /// <remarks>ここに解説を書く</remarks>
        public const int SampleConst = 100;
        
        /// <summary>ここに要約を書く</summary>
        /// <remarks>ここに解説を書く</remarks>
        public event SampleEventHandler SampleEvent;
        
        /// <summary>ここに要約を書く</summary>
        /// <value>ここにプロパティ値の説明を書く</value>
        /// <exception cref="System.Exception">ここに例外に意味を書く</exception>
        /// <remarks>ここに解説を書く</remarks>
        /// <example>
        /// ここに使用例を書く
        /// サンプルコードは以下のように&lt;code&gt;を使う
        /// <code>
        /// class SampleCode {
        ///    ...
        /// }
        /// </code>
        /// </example>
        public string Property {
            set {}
            get { return ""; }
        }
        
        /// <summary>ここに要約を書く</summary>
        /// <param name="Parameter">ここに引数の説明を書く</param>
        /// <returns>ここに戻り値の説明を書く</returns>
        /// <exception cref="System.Exception">ここに例外に意味を書く</exception>
        /// <remarks>ここに解説を書く</remarks>
        /// <example>
        /// ここに使用例を書く
        /// サンプルコードは以下のように&lt;code&gt;を使う
        /// <code>
        /// class SampleCode {
        ///    ...
        /// }
        /// </code>
        /// </example>
        public int Method(string Parameter) {
            return 0;
        }
    }
}
XMLドキュメントの雛型

どう使うか？

ドキュメントにもあるようにコマンドラインやnmakeでコンパイルするときは「/doc:ファイル名」をオプションとして追加してやれば、 そのファイル名でXMLファイルが作成されます。
VisualStudio.NETを使用するときは、プロジェクトのプロパティに「XMLドキュメントファイル」という項目がありますから、 ここにファイル名を設定しておいてビルドすればXMLファイルが作成されます。

ただ、こうしてできたXMLファイルを見ても全然うれしくありません （見てみればわかりますが、ごちゃごちゃしていてとても「ドキュメント」と言えるようなものではありません）。
このXMLファイルを元に「ドキュメント」としての体裁を整えてやる必要があります。
VisualStudio.NETにも標準でついていますが（「ツール」メニューの「Webページのビルドコメント」っていうのがそうです）、 ここではNDocを紹介します。

NDoc

NDocのセットアップ

NDocは、SourceForge.netでオーブンソースで開発されているツールです。 このNDocのページからダウンロードできます（これを書いている時点では1.1cです）。 ndoc-develがソースで、ndoc-installerがインストーラです。

まぁ、インストーラでインストールしちゃうのが簡単です。
ソース（ndoc-devel）でも、slnも付いてますのでVisualStudio.NETで読み込んで「ソリューションのビルド」をするだけでビルドできますし、makefileも付いてますのでコマンドプロンプトからnmakeとすればコンパイルできますけど。 で、GuiディレクトリとConsoleディレクトリの下にbinができあがってるので、これら（exeやdllなど）を好きなところ（Program Filesの下とか）にコピーするだけです （別にコピーしなくてもいいけど）。

NDocの使い方

まず、NDocを起動してみてください（スタートメニューに入ってるはずです。無い場合はNDocGui.exeを起動すればOK）。
それで、

cscを使っている場合
この場合は、「Add」ボタンを押して「Assembly Filename」にアセンブリ（exeかdllのことと思ったらいいです）を、 「XML Doc Filename」にでき上がったXMLファイルを指定してください。

VisualStudio.NETを使っている場合
この場合は、「Project」メニューの「New from Visual Studio Solution」でslnファイルを読み込むことができます。
もちろん、「cscを使っている場合」と同じように個別にアセンブリを読み込んでもOKです。

という風に、ドキュメントを作る対象を選んでやってから好みにあわせて設定するだけです。 「Documentation」メニューの「Build」をすればドキュメントが作成されますから、実際にやってみながら設定していけばいいと思います。
一通りの設定ができたら「Project」メニューの「Save」でNDoc Project Fileを保存しておきましょう。 そうすれば、次回からはこのファイルをOpenするだけでBuildできます。
上記のサンプルコードを「Documentation Type」=「MSDN」でBuildしたファイルを置いておきます （サンプルドキュメント）。

.NET Framework SDKのみの環境（VisualStudio.NETを入れていない環境）の場合、MSDN形式でビルドしようとすると 「hhc.exe がない」とかって例外が出るかもしれません。 この場合は、HTML Help Workshop をダウンロードしてセットアップすれば、その中にhhc.exeがあります。

自動化する

ソースを変更するたびにNDocGui.exeを起動してBuildし直すのは面倒です。 Buildし忘れるとソースとドキュメントがあわないことになっちゃいますし。 そこで、コンパイルするときに同時にドキュメントもBuildするようにしてみます。
NDocをセットアップすると、NDocGui.exeといっしょにNDocConsole.exeも入っています。 NDocGui.exeは上記のように画面で設定しますが、NDocConsole.exeは画面で設定するのと同じことを引数で指定できますし、 NDocGui.exeで保存したNDoc Project Fileを指定することもできます。
cscでmakefileを使っている場合は、

NDocConsole.exe -project=test.ndoc

のようにコンパイルした後にNDocConsole.exeを起動するようにすればいいでしょう （これは、NDoc Project Fileを指定した例です。もちろん、個別に引数で指定しても構いません）。
VusialStudio.NETを使っている場合は、

  1. まず「ファイル」−「プロジェクトの追加」−「新しいプロジェクト」で「Visual C++プロジェクト」−「メイクファイルプロジェクト」を新規作成します。 プロジェクト名は「Document」とかでいいでしょう。ディレクトリとかは適当に。
  2. プロジェクトの新規作成時に出てくる「メイクファイル アプリケーション ウィザード」は全部デフォルトのまま「完了」で構いません。
  3. そうするとソリューションエクスプローラに「Document」が追加されるはずですから、その「Document」を右クリックして「プロパティ」を開いてください。
  4. プロパティのダイアログで「NMake」を選択して、「ビルド コマンドライン」に "NDocConsole.exe -project=test.ndoc" のようにNDocConsole.exeを起動するコマンドを入れてください。
  5. ソリューションエクスプローラの「Document」の下にある「ソースファイル」「ヘッダーファイル」「リソースファイル」は邪魔であれば削除してしまっても構いません （もちろん、あっても構いません）。

こうしておけば、ビルドするたびにドキュメントも生成されます。

どうですか？

実は、上のサンプルコードは「これだけ書いておいてNDocでMSDN形式のドキュメントを作ると、ほとんど.NET Frameworkドキュメントと同じようなものが作れる」 ようにしたものなんです。
コメントを書いておくだけでこんなに立派なクラスリファレンスが作れるんですから、活用しない手はないでしょう。 もちろん、コメントを書いたりメンテしたりする手間はいりますが、ソースとは別にWordとかでクラスリファレンスをシコシコ書くのに比べればはるかに楽だと思います。

[トップ] [目次]
株式会社ディーバ 青柳 臣一
2002/11/22