【フリーツール】XMLコメントのドキュメント化 ～ Sandcastle編 ～

VS / .NET関連ツール

■ 目的

 * VS2010環境において、XMLコメントをjava docのように、ドキュメント化する

 ※なお、XMLコメントについては、以下のサイトを参照のこと。
https://blogs.yahoo.co.jp/dk521123/22290838.html

■ Sandcastle (サンド・キャッスル)とは？

 * XMLコメントからドキュメントを生成する
 * Microsoftから無償で提供されているドキュメントコンパイラ
 * Sandcastleを動作させるには、.NET Framework2.0が必要

補足

 * 「NDoc」は、.NET 4.0では、すでにサポート外とのこと。
http://msdn.microsoft.com/ja-jp/magazine/dd722812.aspx
http://www.atmarkit.co.jp/fdotnet/dotnettips/849aspformview/aspformview.html

■ 環境設定

 1. Sandcastleを以下のサイトからダウンロード（Sandcastle.msi）し、インストールする
http://sandcastle.codeplex.com/
 2. Sandcastle Help File Builderをダウンロードする
   (SHFBGuidedInstallation_XXXX.zip, XXXXはversion。今回は「SHFBGuidedInstallation_1932.zip」)
http://shfb.codeplex.com/
http://oss-ja-jpn.sourceforge.jp/ (日本語版。ただし現時点でVS2010には未対応の模様)
 3. SHFBGuidedInstallation_1932.zipを解凍し、そこから[SHFBGuidedInstallation_1932]-[InstallResources]で
   「SandcastleHelpFileBuilder_1932.msi」をクリックし、Sandcastle Help File Builderをインストールする
 4. 以下のサイトから、HTML Help Workshop(htmlhelpj.exe)をダウンロードし、インストールする
http://www.microsoft.com/download/en/details.aspx?DisplayLang=en&id=21138

参考文献

http://d.hatena.ne.jp/Wacky/20070108/1168237297

■ ドキュメント生成手順

 1. VSのソリューション・エクスプローラで対象プロジェクト(今回は「WebApplication1」)を右クリックし、
    [プロパティ]-[コンパイル]を選択
 2. 「XMLドキュメントファイル」の出力にチェックを入れる
 3. ビルドする
　→[自分の環境]\WebApplication1\WebApplication1\obj\Debug配下に「WebApplication1.xml」ができる
 4. Winodwsの[スタート]-[すべてのプログラム]-
      [Sandcastle Help File Builder]-[Sandcastle Help File Builder GUI]を選択
 5. [File]-[New Project]で、
 6. ProjectExploreでDocumentationSourceを右クリックして
    APIドキュメントを生成するプロジェクトファイル（*.csproj等）を選択する
    これを行わないと、以下のようなエラーが表示されてしまう
----
SHFB: Error BE0039: The project does not have any documentation sources defined
----

 7. [Document]-［Build Project］を選択して、ヘルプを生成する（超時間くう）

参考文献

http://www.atmarkit.co.jp/fdotnet/special/agiledocument01/agiledocument01_03.html
http://d.hatena.ne.jp/aoki1210/20110108/p1

■ トラブルシューティング

ASP.NETで使用するには

 (1) ASP.NETでXMLコメントを出すには、config.webに以下の記述を追加。
～～～～～～～
　・・・
    <system.codedom>
        <compilers>
            <compiler language="vb;vbs;visualbasic;_vbscript"
            extension=".vb"
            type="Microsoft.VisualBasic.VBCodeProvider, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
            compilerOptions="/doc+" />
        </compilers>
    </system.codedom>
</configuration>
～～～～～～～
 (2)Dependency に System.Configuration、同一フォルダの全ファイル (.\*.*) と
    Sources_App_Code内のファイル（.\Sources_App_Code\*.*）を加える

参考文献

http://www.atmarkit.co.jp/bbs/phpBB/viewtopic.php?topic=34813&forum=7
http://d.hatena.ne.jp/with_no_parachute/20091205/1259980666

参考文献

今後、参考にするかも

http://www.lowvism.com/wordpress/?p=722
http://msdn.microsoft.com/ja-jp/library/ms172652.aspx

関連記事

XMLコメントのドキュメント化 ～ Doxygen編 ～

https://blogs.yahoo.co.jp/dk521123/38018326.html

XMLドキュメントコメント(XMLコードコメント)

https://blogs.yahoo.co.jp/dk521123/22290838.html