C＃/API Document for 2.0

Sandcastle のススメ †

　Javaでいうところのjavadocが欲しい場合。。。
　Visual Studio .NET 2003 の頃は、APIリファレンスの作成にはNDoc?を使えばよかったです。しかし、.NET Frameworkが2.0(or 3.0)になってからは、Generics未対応とか、MSDNのBCL(Basic Class Library)へのリンク先が古いままとか、いろいろ不都合が起きました。で、暫定的な NDoc 2005 を使わせて頂いてみても、対応はイマ一歩（ノーブレークスペースの為に多用している文字コード[&#160]が、日本語コードページ上では文字化けしてしまう & Generic対応不十分）で、業務用には使いにくかったりしたわけですよ。
　さらに、NDoc 2.0はリリースされない ということですから、どうすりゃいいのか？と思っていたら、MicrosoftがSandcastle ってドキュメントコンパイラを開発してくれているようです。

　本体はCUIのみなので、バッチ(make_doc.bat)を作るのがいいかな、と思ってたら、別途 Sandcastle Help File Builder ってGUIがありました。この組み合わせは非常に好い！ このGUIの操作性は、完全にNDocGUI互換です。

• NDoc同様、chmファイルを生成できるが、MSDN formatとは異なる。
  • 単なる継承メンバを省略できたり、コード形式をC#, VB.NET, C++.NETから選択できたりする。
• コメント文中の日本語は正しく表示される。ツール自体は日本語未対応。
• Genericも正しく出力される。
• 基本クラスについては、MSDNv2へのリンクを付加できる。
• GACに含まれるアセンブリへの参照設定も、簡単にできる。
• 動作には、.NET Framework 2.0とHTML Help Workshop が必要。
• 2007.02.05現在のバージョンは December 2006 CTP で、まだリリース版ではないが、既に大きな障害はなくなってるんじゃないかなぁ…

　これで、.NETのドキュメントコンパイラ問題は、解決だねっ！ (^o^)/

私的な設定 †

• 利用したソフトウェア
  • Sandcastle(January 2008 Release)
  • Sandcastle Help File Builder GUI 1.6.0.4
  • Microsoft HTML Help Workshop
    • HTML Help 1.xの生成を目的とします。HTML Help 2.0は専用のViewerが別途必要なので嫌いです。
• 手順
  1. 上記全てをインストールし、SHFBを起動
  2. [Add]ボタンで、API Documentを出力するDLL,EXE,XMLファイルを指定する。
  3. Build/Dependenciesに、参照が必要なDLL,EXEファイル、フォルダを指定する。
  4. Build/HelpFileFormatを、「HtmlHelp1x」(Default)にする。
  5. Help File/CopyrightHrefを記入する。
  6. Help File/CopyrightTextを記入する。
  7. Help File/HelpTitleを記入する。
  8. Help File/HtmlHelpNameを記入する。
  9. Help File/Languageを、「日本語（日本）」にする。
  10. Help File/SyntaxFiltersを、「CSharp」のみとする。
  11. Paths/HtmlHelp1xCompilerPathに、HTML Help Workshopのインストールパスを指定する。
  12. Paths/SandcastlePathに、Sandcastleのインストールパスを指定する。
  13. Show Missinf Tags/ShowMissingNamespacesを、「False」にする。
  14. [Build Project]を実施する。