SandCastle 的安裝及使用

以往在 Visual Studio 2003 時，會使用 NDoc 來製作原始碼的說明文件。但這個 Ndoc已經許久沒出新版啦！
現在則被 SandCastle 所取代！

以下是安裝及使用過程

安裝 SandCastle

到 這裡 下載後安裝之。SandCastle 是一個 command line 的工具，因此使用起來特別難過。

安裝 Sandcastle Help File Builder

Sandcastle Help File Builder 是一個 Sandcastle 的 UI 輔助工具。這才是我們最常用的。以下簡稱 SHFB

在 C# 原始碼寫說明

這一點不必再說明了吧！如果需要複習，請見 XML Documentation

打開 xml output

專案在 build 時，預設不會寫出 xml document。必須到每個專案下設定 property。如下圖。

執行 Sandcastle Help File Builder GUI

執行 SHFB 後，首先在右方的 Project Explorer，選取 Documentation Sources 上按右鍵，點擊 Add Documentation Source….，將 solution 加入。

再來設定一些基本的資訊

製作

最後，就開始製作啦！(工具列)

Add Reference

通常，我們會用一些特別的元件，如 SilverLight 等，或在 GAC 上的 assembly。這些不在 solution 目錄，或 bin 目錄下的元件預設是抓不到說明的。此時，很快地會發生錯誤。如下

MREFBUILDER : error : Unresolved assembly reference: System.Windows (System.Windows, Version=2.0.5.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e) required by ProjectStatisticsSL
    Last step completed in 00:00:04.6335
-------------------------------

SHFB: Error BE0043: Unexpected error detected in last build step.  See output above for details.

因此，需要在 Project Explorer 上新增 Reference

 

那要增加什麼呢？看原來的 assembly 資訊。如下圖，將System.Windows對應的 assembly Path 加入即可

看成果

按一下工具列上的放大鏡。就會看到文件囉！