幫 class library 寫文件很重要,但是卻是很煩人的事情,如果用 word 或者弄成網頁,也總是會遇上排版以及維護的問題。而 Visual Studio 內建的 xml documentation 功能又有點貧弱,所以找個好工具真的可以減輕許多困擾並節省時間。網路上可以找到不少類似產生說明文件的工具,但有些是有試用期限的,而這個 Sandcastle Help File Builder 則是免費又好用
目前 Sandcastle Help File Builder 已經搬到 github 上頭去, https://github.com/EWSoftware/SHFB, 如果不想自己 build 整個 project 的,可以到原本在 codeplex 頁面去下載 http://shfb.codeplex.com/已經打包好的 .zip。
解壓縮後有 SandcastleInstaller.exe,執行之後就按步就班安裝,安裝過程中先關掉執行中的 Visual Studio,安裝程式會檢查系統有安裝哪些 Visual Studio 版本,此外安裝程式會在畫面上顯示哪些東西需要安裝,就放心地一路裝下去就好。
安裝完之後在功能表內就會多了 Sandcastle Help File Builder 的資料夾了
開始進行產生說明文件前要先在 Visual Studio 的 project property 內的 build options 設定將 xml documentation file 選項勾起來,並編譯該 project 後會產生該 class library 的 xml document.
再來啟動 Sandcastle Help File Builder 後,把該 project file (.csproj)指定到 References 底下,並把編譯出來的 DLL 與 xml document 放到 Documentation Sources 下。
如果要連 private member fields/methods/etc. 都放到產生的 help file 中,要去 Visibility 內設定。