Visual Studio 2005以降でフリーで使用できるAPIドキュメントツールは以前はNDocがあったと思うのですが、いまはSandcastleが有力なツールだと思います。Sandcastleを使用すると、MSDNドキュメントのようなAPIドキュメントをアセンブリとビルド時に作成するXmlドキュメントファイルから生成してくれます。Sandcastle Help File Builderを使用すると、コンソール操作ではなく、GUIを使用してAPIドキュメントを簡単に作成できるようになります。

確認環境

  • Widows Vista Enterprise
  • Visual Studio 2008 Professionalがインストール済み

1. Sandcastleのインストール

SandcastleをCodePlexのサイトからダウンロードします。下記のリンクからSandcastleの最新版のダウンロードをします。ページの右端のダウンロードのリンクもしくは、Releasesタブをクリックすると最新版のダウンロードページに遷移できます。

http://www.codeplex.com/Sandcastle

記事作成時に最新のバージョンはMay 2008 Release (Version 2.4.10520)でした。Sandcastle Help File Builderでサポートされているバージョンなので、そのままSandcastle.msiをダウンロードします。

ローカルファイルにSandcastle.msiをダウンロードして、デフォルトのままインストールすればインストール完了です。

2. Sandcastle Help File Builderのインストール

Sandcastle Help File BuilderをCodePlexのサイトからダウンロードします。下記のリンクからSandcastle Help Builderの最新版をダウンロードします。ページ右端のダウンロードリンクもしくはReleaasesタブをクリックすると最新版のダウンロードページに遷移できます。

http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=10445

記事作成時の最新バージョンは1.7.0.0で、ダウンロードページのRelease NotesにサポートバージョンがSandcastle May 2008 Release (v2.4.10520)となっているので、インストールしたSandcastleのバージョンが使用できることが確認できます。

Sandcastle Help File Builder Installerのダウンロードリンクからzipファイル(記事作成時点でのファイル名SandcastleBuilderSetup_1700.zip)をローカルにダウンロードして、zipファイルを展開し、SandcastleBuilderSetup.msiを実行して、デフォルト設定のままインストールします。

以上で、必要なプログラムのインストールは完了です。簡単ですばらしいです。

3. APIドキュメント作成用のアセンブリとXmlファイルの作成

APIドキュメントに作成なアセンブリはexeもしくはdllのアセンブリと、ソースコードのクラスやメソッドのコメントに記載した内容を含むxmlドキュメントファイルです。ビルド時にXmlドキュメントファイルを出力するには、プロジェクトのプロパティ画面を開いて、Buildタブを選択し、xmlファイルを出力するようにXml documentation fileにチェックをします。

 

 

APIドキュメントを生成するすべてのプロジェクトに対して、Xmlドキュメントファイルを出力するようにし、ソリューションのビルドを行うと、dllとxmlファイルがビルドファイルの出力先に作成されます。

WebサイトプロジェクトはXMLファイルを出力するようにできません(Web Applicationプロジェクトは作成できます)。WebサイトプロジェクトでAPIドキュメントを作成したい場合は、Sandcastle Help File Builderのヘルプを開いて、Contentsタブから、Getting Started→Documenting Web Projectsの順でヘルプを開き、ヘルプの内容にしたがって対応を行えば、XMLファイルを出力できると思います。(確認はしていません)

4. APIドキュメントの作成

スタートメニューからSandcastle Help File Builder GUIを選択して、Sandcastle Help File BuilderのGUI版を起動します。Addボタンを選択して、APIドキュメントを作成するアセンブリを選択します。GACに存在しない場合は、依存するアセンブリとxmlドキュメントファイルをすべて含める必要があります。依存するdllでAPI作成対象ではない場合、後述するDependenciesにアセンブリを登録します。Namespacesボタンをクリックすると、出力するnamespaceをチェックボックスで制御できます。デフォルトで名前空間のない、グローバルなクラスのAPIドキュメントは作成しないようになっているので、必要に応じてチェックするようにします。

 

log4netなど、APIドキュメント作成対象ではない依存するアセンブリは中央のProject PropertiesのDependenciesを選択して、追加するようにします。

出力言語をJapanese(日本語)にして、ドキュメント作成のプロジェクトを適当な場所に保存します。次に、メニューのDocumentation→Build Projectでヘルプファイルを作成します。Outputペインに大量のログが出力されてファイルが作成されます。時間は多少かかります。

既定では、保存したプロジェクトの直下にHelpフォルダにDocumentation.chmファイルが作成されるので、ファイルを開くと、APIドキュメントが作成されていることが確認できます。

以上でHtml Help 1.x形式のヘルプファイルが作成できるようになりました。

とっても簡単ですばらしいです。APIドキュメントを作成すると、いかに自分がコメントを書いていないのかがよくわかりますorz。

おまけ。ドキュメントエクスプローラからHtmlHelp2形式のヘルプを閲覧する方法

Visual StudioのSDKをインストールすると、HtmlHelp2形式のファイルをSandcastleから作成できるようになります。Visual Studio 2008 SDKは下記のリンクからダウンロードできます。

http://www.microsoft.com/downloads/details.aspx?familyid=30402623-93ca-479a-867c-04dc45164f5b&displaylang=en

Sandcasthle Help File BuilderのHelp File FormatをHtmlHelp2.xに指定し、ヘルプファイルのプロジェクトをビルドすると拡張子がHxSのファイルが作成されます。他にもファイルが作成されますが、HtmlHelp2のドキュメントなどを参照して下さい。作成されたヘルプをMicrosoft Namespace#2.0を使用してドキュメントエクスプローラ用のネームスペースに登録したします。下図のファイルメニュー→Openで、HxSファイルを開くと自動で登録されます。下図でHelp Viewsをクリックすると、ここからヘルプを閲覧することができます。コマンドラインからでも登録はできると思いますが調べていないです申し訳ありません。

 

 

登録後、以下の用にコマンドプロンプトに入力することで、登録されたhxsファイルをドキュメントエクスプローラから参照できます。

>"C:\Program Files\Common Files\Microsoft Shared\Help 8\dexplore.exe"  /helpcol ms-help://documentation.hxs

 

 

ドキュメントエクスプローラに統合する方法はいくつかあるようですが、一例として紹介させていただきました。