close

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 階段,所以未來功能特色都沒有底定,以下幾個建議:

  1. 說明文件要真正能用,還是得靠作者勤於撰寫,工具只能將你寫好的內容輸出。
  2. Sandcastle 目前提供的都是命令行工具,假如不習慣命令行,建議到網路搜尋下載免費的 GUI 介面,我自己用的是 Sandcastle Help File Builder
  3. 輸出為 CHM 檔案 (HTML 1.x help files) 是一個不錯的選擇,作業系統也內建支援這種說明檔案。但你需要 HTML Help Workshop,裡面有編譯工具。
  4. 我不建議輸出為 HxS 檔案 (HTML 2.x help files),因為作業系統並不支援這種檔案,所以必須安裝 Visual Studio 2005 並且註冊編譯出來的文件,或是另外安裝的三方開發的免費瀏覽工具,總之並不方便。假如要製作 HxS 檔案,請下載安裝 VS2005 SDK,裡面有編譯工具。

開發 .NET 程式時我兩種工具都並行使用,Doxygen 用來唬爛老闆 ,Sandcastle 拿來真正使用 

arrow
arrow
    全站熱搜
    創作者介紹
    創作者 unix 的頭像
    unix

    程式開發ㄅㄆㄇ -歡迎光臨 Inuiüni 幼稚園

    unix 發表在 痞客邦 留言(0) 人氣()