.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をインストールしてみよう。
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ファイル)が出力されるようになる。
以上でNDocを使うための準備は完了した。次にNDocを実際に使ってみよう。
NDocの使用方法
NDocの使い方は簡単だ。ここでは基本的な作業の流れについてのみ説明する。
まず[スタート]メニューから[プログラム]−[NDoc]−[NDoc]を選択してNDocを起動する。そして次の画面例のように、[Add]ボタンを押して[アセンブリ・ファイルとXMLドキュメント・ファイルの追加(Add Assembly Filename and XML Documentation Filename)]ダイアログを開き、プロジェクトのビルドにより出力されたアセンブリ・ファイルとXMLドキュメント・ファイルを指定する。
アセンブリ・ファイルとXMLドキュメント・ファイルの指定 | |||||||||||||||
APIリファレンスを出力したいプログラムのアセンブリ・ファイルとXMLドキュメント・ファイルを指定する。 | |||||||||||||||
|
後は、ツールバーの[ドキュメントのビルド(Build Documentation)]ボタンをクリックしてAPIリファレンスのビルドを行い、ツールバーの[ドキュメントの参照(View Documentation)]ボタンをクリックしてAPIリファレンスを表示すればよい。
APIリファレンスのビルドと参照 | ||||||||||||
APIリファレンスを生成するにはビルドを行う必要がある。ビルドしたAPIリファレンスはNDocから起動して参照することができる。 | ||||||||||||
|
以上の操作により、冒頭で紹介したようなMSDNライブラリ風のAPIリファレンスが表示されるはずだ。
なお、ソース・コード中に記述する「ドキュメント コメントのタグ」の内容や記述方法については、MSDNライブラリ「XMLドキュメント」や冒頭で紹介した「Visual C# .NETでAPIリファレンスを作る(前編)/(後編)」などを参照していただきたい。NDocのメニュー・バーから[Help]−[Documentation Tags Reference]を選択することで表示される「NDoc でサポートするタグ」も参考になる。
カテゴリ:開発環境&ツール 処理対象:APIリファレンス カテゴリ:クラス・ライブラリ 処理対象:Win32 API |
|
「.NET TIPS」 |
- 第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用のアドイン。プレゼンテーション時の字幕の付加や、多言語での質疑応答、スライドの翻訳を行える
|
|