チリペヂィア

リンクフリー。サンプルコードなどは関連記事内でライセンスについて明示されない限り商用利用なども自由に行って構いませんが、自己責任でお願いします。またこれら日記内容の著作権自体は放棄していません。引用部分については引用元の権利に従ってください。

.Net用の自動文書化ツール Sandcastle Help File Builder に挑戦

VB .NET

内部仕様文書化用にNDocを使ってみようと思ったらメンテが止まりかけのようで、Sandcastleを見つけました。使い方もそんなに難しくなさそう。早速挑戦。

入手先とインストール

Sandcastle Help File Builder (CodePlex)
もともとMS謹製のコマンドラインツールSandcastleにフリープロジェクトでGUIをつけたものがSHFBのようですね。SHFBにはSandcastleのインストーラが同梱されているので、対話形式で一緒に自動インストールしてもらえます。

ところで私は最初自動インストーラに気付かずに個別のインストーラから手動でインストールしたところ、後で「アレが無いコレが無い」とやたらエラーを吐かれてしまいました。素直に自動インストーラを使った方が良いようです。

それと、関連ファイルがちょっと複雑なので、いくつか追加インストールする必要があるかもしれません。参考までに私の選択したオプションは以下。

  • とりあえず*.chmを出力するのに HTML Help Workshop が必要なのでインストール（直前に手動インストールしていたので、無い時に自動インストーラが何か言って来るかは不明）
  • VS2005/2008がないと*.HxS(MSHelp2形式)が出力できないらしい？でも、今更必要性が微妙なのでスルー
  • 2010スタイル（現行のMSDNスタイル）にはVS2010のフォルダからdev10.mshcをコピーする必要がある。VB.Net2010を入れていたので、自動インストーラのダイアログからコピーを実行。
  • Expressだったので拡張機能マネージャはインストールできず。

プロジェクト作成とビルド

さっそくプロジェクトを作成します。SandcastleBuilderGUI.exeを起動。

　File>New Projectからプロジェクトを新規作成します。出力形式にもよりますが、そこそこ複雑な階層を作る時があるので、適当にドキュメントプロジェクト専用階層を作っておく事をオススメします。


　Project Explorer＞[Project名]＞Documentation Sourcesを右クリックして「Add Documentation Sources...」をクリック。文書化対象の実行ファイル(またはdll)を選択。

　ちなみに、文書化するプロジェクトはコンパイルオプションでXML出力オプションをチェックしてビルドしておいて下さい、との事（VBはVSのGUI側では設定が存在せず、強制的にONなんですけど、C#は選択できるらしい）。

　というのも、ビルドされた実行ファイルには、詳細な型情報なんかが全てリバースエンジニアリングの容易な状態で格納されていて、さらにビルド時に一緒に出力されるXMLにはソースコード側のコメント記述が転写されているので、この両者をあわせると自動で文書化できる、というカラクリになっている模様。つまりXMLがないとコメントが取れないんじゃないかしら。

　また読み取り元には実行ファイルの直接指定だけでなく、*.slnファイルなども対応していました。Documentation Sourcesを右クリックして「Add Documentation Sources...」から、対象の*.slnと、それに含まれていてスキャンしたい*.*projを両方指定して、Debug/Releaseや対象CPUなどを選択すると読み取れます。

さて文書化対象の実行ファイルとXMLファイルが登録されたら、適当にプロパティをいじります。お好みで。以下は私の設定。

  • Build＞HelpFileFormatをWebsiteのみチェック
  • Help File＞PresentationStyleをvs2010に
  • Visibility＞ApiFilterで、出力したいクラスだけチェック（解析に結構時間がかかります）

　そしてDocumentation＞Build Projectを実行。結構時間がかかります。

　出来ました。これがvs2010スタイルWebsite形式。ところどころ表示が荒ぶってはいますが、自動でコレだったらなかなかのもの。

ソースコードコメント用に使えるXMLタグの概要一覧は以下を参考にしました。
http://www.atmarkit.co.jp/fdotnet/special/agiledocument01/agiledocument01_03.html

MSDNのドキュメントコメントとして推奨されるXMLタグ一覧
http://msdn.microsoft.com/ja-jp/library/ms172653%28v=vs.100%29.aspx

ちなみに解析したソースコードはこんな感じ。

Partial Public Class Logic

    ''' <summary>
    ''' デリゲート<see cref="Echoes.Handler"/>をリスト管理するクラス。
    ''' </summary>
    ''' <typeparam name="TArgs">この型によって<see cref="Echoes.Handler"/>デリゲートを定義します。</typeparam>
    ''' <remarks>
    ''' <para>デリゲートリストを構築します。<br/>マルチキャストデリゲートと似ていますが、以下の点で異なります。
    ''' <list type="bullet">
    ''' <item><description>二重登録が禁止される</description></item>
    ''' <item><description>デリゲートが登録済みか検査できる</description></item>
    ''' <item><description><see cref="Echoes.Handler"/>デリゲートしか登録できない</description></item>
    ''' </list>リスト操作にマルチキャストデリゲートが与えられると、個別に解体されてから評価されます。</para>
    ''' <para>リスト管理はスレッドセーフです。ただし、<see cref="Echoes.Echo"/>内からリスト編集操作をコールするとデッドロックします。</para>
    ''' <para><paramref name="TArgs"/>が<see cref="EventArgs"/>を継承するときは<see cref="UniqueEvents"/>を利用してください。</para>
    ''' </remarks>
    Public Class Echoes(Of TArgs)

        ''' <summary>
        ''' <see cref="Echoes"/>でリスト管理するデリゲートを定義します。この型に適合するデリゲートがリストとして管理されます。
        ''' </summary>
        ''' <param name="e"><paramref name="TArgs"/>を引数にもつデリゲートが定義されます。</param>
        ''' <remarks><see cref="Echoes"/>でリスト管理するデリゲートでは戻り値は返せません。</remarks>
        Public Delegate Sub Handler(ByVal e As TArgs)

        ' <中略>

    End Class

End Class

おぉ…「ソースコードには読みやすいようにコメントをつけましょう」なんて入門書の記述が随分遠くに感じられますね。内部作業者に読みやすいコメなんて、この宇宙には存在しなかったんや！納品の一環です！

しかし、Htmlで出力してしまうとバージョン管理しにくいったらないですね…作業中は基本的にSHFBのプロジェクトファイルだけを共有管理して、出力は各人ローカル側で持つのが本当なのかな？