.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」を紹介する。

* MSDN「Microsoft Help Technologies」にある「Visual Studio .NET Help Integration Kit(Microsoft Help 2形式)」や「HTML Help Workshop(HTML Help 1.4形式)」を使えば、HTMLヘルプ形式に変換は可能。

 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」と書かれているインストーラ付のパッケージだ。

 ダウンロードした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 でサポートするタグ」も参考になる。End of Article

カテゴリ:開発環境&ツール 処理対象:APIリファレンス
カテゴリ:クラス・ライブラリ 処理対象:Win32 API
 
この記事と関連性の高い別の.NET TIPS
[ASP.NET]任意のXMLファイルからサイト・メニューを作成するには?
このリストは、(株)デジタルアドバンテージが開発した
自動関連記事探索システム Jigsaw(ジグソー) により自動抽出したものです。
generated by

「.NET TIPS」


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 記事ランキング

本日 月間