ふにゃるんv2

もとは、http://d.hatena.ne.jp/Wacky/

Sandcastle Help File Builder を使って、ソースコードからドキュメントを自動作成しよう

.NET

Sandcastle というのは、ソースコードの構造やコメントを元に、ドキュメント(APIや内部説明書)を自動作成してくれるソフトです。
類似のソフトとして、doxygenやNDocがあります。
今回は、Sandcastle と 支援ソフトの Sandcastle Help File Builder の使い方について、簡単に説明します。

まずは概要

Sandcastleには、以下の特徴があります。

  • MSDN風のHTML Help形式(.chm)のドキュメントを作成してくれます。
  • .NET 2.0に対応しています。
  • Microsoft自身が対応してくれています。
    VS SDK 4.0 December CTP に同梱されたり、単独で配布しています。
  • 日本語を使っても大丈夫のようです。


Sandcastleについて、先行で調べてらっしゃる方については、以下が参考になると思います。

Sandcastleのインストール

Sandcastle自体のインストール方法は、以下の2つがあります。


Sandcastle自体は、コマンドラインで動かすツールです。
インストールすると、幾つかのEXEファイルが配置されますが、単体で入れた場合と、VSSDK 4.0を入れた場合で、配置場所が若干異なります。

  • 単体で入れた場合、"C:\Program Files\Sandcastle\ProductionTools" にEXEファイルが置かれます。
  • VSSDK 4.0を入れた場合、"C:\Program Files\Visual Studio 2005 SDK\2006.12\VisualStudioIntegration\Tools\Sandcastle\ProductionTools" にEXEファイルが置かれます。

ちなみに、ファイルの日付を比較してみたんですが、VSSDK 4.0のものより、Downloadセンターから単体でゲットできる方が、新しい感じです。
(バイナリファイルのアセンブリバージョンや、ファイルスタンプが単体版の方が新しかったです)

Sandcastleの問題

Sandcastleの問題は、使い方が今一わかんない点にあります。
特に私のように、英語なんてわかんねーっす な人にとって、致命的です。


先行で調べてらっしゃる方の記事を見て、ちょきちょき動かしてみたんですが、私にはダメでした。
そこで、支援ツールが欲しいよぅ、となる訳です。

Sandcastle Help File Builderという支援ツール

諸先輩方のBlogを見ていると、色々と支援ツールが出ている事に気付きます。
パッと並べると、以下が挙げられます。


今回は、この中から Sandcastle Help File Builder を試してみます。

Sandcastle Help File Builderを使って、ドキュメントを作成するまでの手順

以下、Sandcastle Help File Builder を使って、ドキュメントを作成するまでの手順を示します。


1.Sandcastle Help File Builderをダウンロードする
Sandcastle Help File Builderに行き、右上欄からZIPファイル(SandcastleBuilderSetup.zip)をダウンロードします。


2.Sandcastle Help File Builderをインストールする
SandcastleBuilderSetup.zip を展開すると、セットアップファイル(SandcastleBuilderSetup.msi)がありますので、これをインストールします。

Sandcastle1
Sandcastle1 posted by (C) wackyさんの写真


3.ドキュメント化の対象となるプロジェクトに対する設定を行う
早速、Sandcastle Help File Builder を実行したい所ですが、ちょっと待って下さい。
ドキュメント化対象のプロジェクトに対して、以下の設定が必要です。

  • プロジェクト設定で、「XMLドキュメントファイル」の出力にチェックを入れる
    Sandcastle3
    Sandcastle3 posted by (C) wackyさんの写真
  • ビルドする
    Sandcastleは、バイナリを解析する風な事を書いています。要らないかも知れませんが、念の為。


4.Sandcastle Help File Builderを起動する
設定が終わったら、早速 Sandcastle Help File Builder をスタートメニューから、"Sandcastle Help File Builder" → "Sandcastle Help File Builder"の順に起動します。


5.プロジェクトを作成する
"Project"→"New Project from Visual Studio Project..."で、ドキュメント化対象のプロジェクトファイル(*.sln)を指定し、プロジェクトを作成します。
プロジェクトファイル名は、*.shfb になるようです。

Sandcastle5
Sandcastle5 posted by (C) wackyさんの写真

なお、ドキュメント化対象のプロジェクト内で、Debug版とRelease版を作っていると、どっちを対象にするか聞いてきます。

Sandcastle6
Sandcastle6 posted by (C) wackyさんの写真


6.ビルドする
早速、"Documentation"→"Build Project"で、ファイルをビルドします。

Sandcastle8
Sandcastle8 posted by (C) wackyさんの写真


7.ビルドエラーが出た！
私の場合、早速エラーが出ました。

Sandcastle7
Sandcastle7 posted by (C) wackyさんの写真


下の方、読み難いですが、以下のように書かれています。

Error: Unresolved assembly reference: Microsoft.VisualBasic.Compatibility (Microsoft.VisualBasic.Compatibility, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a) required by TxtReader

BUILD FAILED: Unexpected error in last build step.  See output above for details.


う〜む、FileListBoxを使ったのが影響しているか…と思いつつ、Sandcastle Help File Builder に付属のヘルプファイルを開いて検索すると、そのものズバリな答えが書いていました。

Why does my build fail with an Unresolved assembly reference error?
If the build fails in the Generating reflection information step with an error that starts "Error: Unresolved assembly reference", you need to add the named assembly as a dependency. This is done by adding a reference to it using the Dependencies project property. See the Dependencies Property help topic for more information.


要するに、"Project Properties"欄の、"Build"→"Dependencies"に、依存ファイルを指定しろ。って事みたいです。
早速指定。

Sandcastle9
Sandcastle9 posted by (C) wackyさんの写真


指定後、再度ビルドをかけると、暫くして完了した模様です。

Sandcastle10
Sandcastle10 posted by (C) wackyさんの写真


8.どんなドキュメントファイルが出来上がるか？
"Project Properties"欄を弄ると、細かく設定できるっぽいんですが、デフォルトのまま出力させると、以下のようなドキュメントが出来上がります。
(ファイルは、Documentation.chm でした)

Sandcastle11
Sandcastle11 posted by (C) wackyさんの写真

どうもデフォルトでは、public属性のみが説明に追加されるようですね。
出力内容から察するに、デフォルトではライブラリ用にチューニングされている感じです。


9.C# / VB / C++の自動形式出力
パッと見て、面白いなと思ったのが、右上のコンボボックスの"C#"って所。
ここを切り替えると、関数の説明が、C#形式／VB形式／C++形式の表示に自動的に切り替わります。


こりゃぁ、便利ですね。

資料

Sandcastle以外にも、ドキュメンテーションツールはある訳です。
なので、参考URLをば。


個人的には、doxygenの各種フォーマット(RTF, XML, HTML, HTML Help, PDF, man)に出力可能な点が気に入っています。
Pythonにも対応していますしね。

まとめ

という訳で、まとめです。

  • Sandcastleは、Sandcastle Help File Builder と組み合わせて使うと便利です。
    というか、私には、これと組み合わせて使わないと、Sandcastle単体では使いこなせませんでした。
  • 日本語の出力に対応しているので、安心して使えます。
  • ソースコードにはコメントを書きましょう。