Tweet

.NET TIPS C#でMSDNライブラリ風のAPIリファレンスを作成するには？ デジタルアドバンテージ 2004/07/16

　Visual Studio .NET（以降、VS.NET）のC#環境であるVisual C# .NETでは、標準機能として、次の画面のようなAPIリファレンス（VS.NETでは「コード・コメントWebレポート」と呼んでいる）を作成できる（詳しくは「Visual C# .NETでAPIリファレンスを作る（前編）／（後編）」を参照されたい）。このAPIリファレンスは、ソース・コード内にコメント文として記述されたXMLタグ（「ドキュメント・コメントのタグ」と呼ばれる）を基に作成されたものだ。

VS.NETの「コード コメントWebレポート」

VS.NETにはAPIリファレンス（「コード コメントWebレポート」と呼ばれる）を出力する機能が標準搭載されている。このAPIリファレンスは、VS.NETのIDEにあるメニュー・バーの［ツール］−［Webページのビルド コメント］から出力できる。

　しかしこのAPIリファレンスでは、MSDNライブラリのページ最下部にあるような「参照」の項目が追加できなかったり、MSDNライブラリのようなHTMLヘルプ形式（.chmファイル）を出力できなかったり*と、使い勝手が悪いところがある。そこで本稿では、このような不満を解消する無償のAPIリファレンス作成ツール「NDoc」を紹介する。

　NDocは、MSDNライブラリ風APIリファレンスのHTMLヘルプ・ファイルを生成するためのツールだ。このツールを使えば、次の画面のようなAPIリファレンスを作成できる。

NDocによるAPIリファレンス

NDocならHTMLヘルプ形式のMSDNライブラリ風APIリファレンスを作成できる。

NDocでは［参照］に独自の項目を追加することができる。「参照」項目に対応するドキュメント・コメントの<seealso>タグはVS.NETにより標準サポートされている。しかしVS.NETの「コード コメントWebレポート」では、なぜか「参照」項目がAPIリファレンス内に表示されない。

　それでは、さっそくこのNDocをインストールしてみよう。

NDocのインストール

　NDocは次のサイトからダウンロードできる。ここでダウンロードするファイルは、「ndoc-jp-installer」と書かれているインストーラ付のパッケージだ。

• SourceForge.jp：NDOC日本語版（http://sourceforge.jp/projects/ndoc-jp/）

　ダウンロードしたNDocのインストーラ（NDocWebSetup_jp.exe）を実行すればインストールは完了する。途中で「AUTHENTICODE署名を検出できません。」といったセキュリティ警告が表示される場合があるが、特に問題なければそのまま続行して、指示どおりに最後までインストールを完了させてほしい。

　インストールが終わればNDocを使うことはできるが、実際にAPIリファレンスを生成するためには、あらかじめ必要なファイルを準備しておく必要がある。

XMLドキュメント・ファイルの出力

　NDocで必要となるファイルは、Visual C# .NETのプロジェクトに含まれる以下の2種類のファイルだ。

• アセンブリ・ファイル（ビルドにより作成されるEXEファイルやDLLファイル）

• XMLドキュメント・ファイル（ビルド時にドキュメント・コメントを基に抽出されるXMLファイル）

　XMLドキュメント・ファイルの方は、プロジェクトの設定がデフォルトのままでは出力されないので、あらかじめプロジェクトのプロパティを変更しておく必要がある。それには、次の画面のように、プロジェクトの［プロパティ ページ］ダイアログで［XML ドキュメント ファイル］項目に「出力するファイル名（もしくはファイル・パス）」を入力すればよい。

XMLドキュメント・ファイルの出力設定

プロジェクトの［プロパティ ページ］ダイアログで、ビルド時にXMLドキュメント・コメントのファイルが出力されるように設定する。

［構成プロパティ］フォルダの中にある［ビルド］項目を選択する。 　 ［出力］項目の中にある［XML ドキュメント ファイル］にファイル名（もしくはファイル・パス）を入力する。これにより、XMLドキュメント・ファイル（.xmlファイル）が指定した名前で（もしくは場所に）出力されるようになる。

　この設定により、ビルドを行った後には［XML ドキュメント ファイル］に指定したファイル名（もしくはファイル・パス）のXMLドキュメント・ファイル（.xmlファイル）が出力されるようになる。

　以上でNDocを使うための準備は完了した。次にNDocを実際に使ってみよう。

NDocの使用方法

　NDocの使い方は簡単だ。ここでは基本的な作業の流れについてのみ説明する。

　まず［スタート］メニューから［プログラム］−［NDoc］−［NDoc］を選択してNDocを起動する。そして次の画面例のように、［Add］ボタンを押して［アセンブリ・ファイルとXMLドキュメント・ファイルの追加（Add Assembly Filename and XML Documentation Filename）］ダイアログを開き、プロジェクトのビルドにより出力されたアセンブリ・ファイルとXMLドキュメント・ファイルを指定する。

アセンブリ・ファイルとXMLドキュメント・ファイルの指定

APIリファレンスを出力したいプログラムのアセンブリ・ファイルとXMLドキュメント・ファイルを指定する。

［Add］ボタンをクリックすると［アセンブリ・ファイルとXMLドキュメント・ファイルの追加（Add Assembly Filename and XML Documentation Filename）］ダイアログが表示される。 　 プロジェクトに含まれるアセンブリ・ファイルを指定する。 　 プロジェクトに含まれるXMLドキュメント・ファイルを指定する。 　 ［OK］ボタンをクリックして設定内容を確定し、ダイアログを閉じる。 　 APIリファレンスを出力するプログラム（アセンブリ・ファイル）が登録される。

　後は、ツールバーの［ドキュメントのビルド（Build Documentation）］ボタンをクリックしてAPIリファレンスのビルドを行い、ツールバーの［ドキュメントの参照（View Documentation）］ボタンをクリックしてAPIリファレンスを表示すればよい。

APIリファレンスのビルドと参照

APIリファレンスを生成するにはビルドを行う必要がある。ビルドしたAPIリファレンスはNDocから起動して参照することができる。

ツールバーの［ドキュメントのビルド（Build Documentation）］ボタンをクリックすると、APIリファレンスのビルドが行われる。 　 ツールバーの［ドキュメントの参照（View Documentation）］ボタンをクリックすると、ビルドで生成されたAPIリファレンスが表示される。 　 NDocではMSDNライブラリ風のAPIリファレンスだけでなく、JavaDoc風のAPIリファレンスなど、さまざまなタイプのものを生成できる。 　 このプロパティ設定を変更することで、APIリファレンスの構成内容（例えば、ファイルの出力場所など）をカスタマイズできる。

　以上の操作により、冒頭で紹介したようなMSDNライブラリ風のAPIリファレンスが表示されるはずだ。

　なお、ソース・コード中に記述する「ドキュメント コメントのタグ」の内容や記述方法については、MSDNライブラリ「XMLドキュメント」や冒頭で紹介した「Visual C# .NETでAPIリファレンスを作る（前編）／（後編）」などを参照していただきたい。NDocのメニュー・バーから［Help］−［Documentation Tags Reference］を選択することで表示される「NDoc でサポートするタグ」も参考になる。

この記事と関連性の高い別の.NET TIPS Win32 API呼び出しを手軽に記述するには？ このリストは、（株）デジタルアドバンテージが開発した 自動関連記事探索システム Jigsaw（ジグソー） により自動抽出したものです。 generated by

「.NET TIPS」

＠ITメールマガジン　新着情報やスタッフのコラムがメールで届きます（無料）

RSSフィード