Inui 程式開發╭★.NET 程式開發文件
.NET 程式開發文件
VS2003 有過一個工具可以將加在程式碼上的說明文字 (XML 規格) 轉為 HTML 報告,方便程式設計人員分享設計文件,但是 Visual Studio 2005 卻把這個工具拿掉了!變通的作法有兩個 (以上):
Doxygen 1.5 以上也支援處理 C# 程式語言,開發者還是一樣依照微軟的規格撰寫說明文字。它可以直接 parsing 目錄內的所有 C# 程式碼,不需要先產生 XML 文件,可以輸出多種規格的文件,例如 HTML、LaTex、RTF,效能極佳。我最喜歡用它唬弄老闆的功能:將它搭配 Graphviz 輸出包含有 UML 圖形的文件,整份厚達數百頁 RTF 說明文件。程式設計人員絕對不會喜歡這種數百頁的文件,Hyperlink 也很不方便,但是老闆反正看不懂,他說:一份 Word 文件就涵蓋所有說明,多好!
Microsoft 的 Sandcastle 計畫,就是將輸出的 XML 設計文件,再進一步加工成為其他格式 (這個方向與 NDoc 相同,但 NDoc 已經停止開發,所以不予推薦)。產出物看起來就像 MSDN 的文件,所以相當方便看慣 MSDN 說明文件的程式設計人員。預設的格式是 HTML,但也可以經過編譯工具,製作 CHM 或 HxS 文件。Sandcastle 還在 CTP 階段,所以未來功能特色都沒有底定,以下幾個建議:
- 說明文件要真正能用,還是得靠作者勤於撰寫,工具只能將你寫好的內容輸出。
- Sandcastle 目前提供的都是命令行工具,假如不習慣命令行,建議到網路搜尋下載免費的 GUI 介面,我自己用的是 Sandcastle Help File Builder。
- 輸出為 CHM 檔案 (HTML 1.x help files) 是一個不錯的選擇,作業系統也內建支援這種說明檔案。但你需要 HTML Help Workshop,裡面有編譯工具。
- 我不建議輸出為 HxS 檔案 (HTML 2.x help files),因為作業系統並不支援這種檔案,所以必須安裝 Visual Studio 2005 並且註冊編譯出來的文件,或是另外安裝的三方開發的免費瀏覽工具,總之並不方便。假如要製作 HxS 檔案,請下載安裝 VS2005 SDK,裡面有編譯工具。
開發 .NET 程式時我兩種工具都並行使用,Doxygen 用來唬爛老闆 ,Sandcastle 拿來真正使用
。