在開發專案時，程式人員最不喜歡的無非是：
- 寫文件。
- 對方沒寫文件。
- 心裡OS：「寫Code都來不及，還要同步維護文件」，導致文件就這樣爛了....
因為上述不少的問題下，Live Document 需求就由然而生。
我們期望找到「依據實際的Code與註解，來動態產生文件」的方法；接下來就來說明如何實作。
前言
無論是公司 or 小團隊的專案，缺少相關文件說明時，會讓大家在使用上多少不便，尤其底層元件運用頻繁，更需要使用文件來協助開發。
而文件內容，我們希望依據現有專案Code來動態產生；這樣的文件可以反應真實情況，且不怕年久失修。因為有以上原因，所以開始進行評估作業。
評估
stackoverflow：C# documentation generator
依據 stackoverflow 上面的推薦；首先選擇了 Sandcastle 這套開源又可免費使用的工具。
需要注意的是：工具之所以能動態產生文件，主要依據我們在開發.NET程式時，所加註的 XML註釋，如：
/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass{}
在專案中相關的 summary, parameters , type, returns 等說明，開發人員於開發階段，都應該正確輸入，若有遺漏也要記得補上。如此文件產生時，才會更加完善。
使用方式
1. 安裝 Sandcastle、Sandcastle Help File Builder 工具 (可參閱此篇記錄)
2. 開啟「專案建置時產出XML文件檔案」功能。(VS開啟專案，在專案上點擊滑鼠右鍵 → 屬性 → 建置頁籤 → 勾選 XML文件檔案 → 儲存後，進行編譯)
3. 有了XML之後，再來就是使用工具，試著產生文件看看。
- 建立新文件專案 (設定文件的專案結構、文件型態)
- Documentation Source 滑鼠右鍵 → Add Documentation Source → 找到剛剛的 dll 與 xml，選擇 WebSite 型態的文件。
- Help File：自訂title、輸出程式語言模式 設定。(其他頁籤的設定，可是需求再進行設定) → 儲存後，即可編譯。
- 開始建置文件。(建置成功後，會產生Help資料夾，內有我們選擇的WebSite網站)
- 查看一下產出的文件成果。
4. 指令化。為了方便整合至 CI Server 環境，我們可以透過以下指令來處理。
<# 產生.NET Library文件 #>
#Sandcastle Help File Builder 根目錄 (請確認執行路徑)
$SHFB_Root_Path = "/property:SHFBROOT=C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder"
#Sandcastle Help File Builder 專案目錄 (請自行調整路徑)
$SHFB_Project_Path = "D:\DownloadTempR\Document\MyStorage\MyStorage_HelpDoc.shfbproj"
#文件站台 (請自行調整路徑)
$Result_WebSite = "D:\DownloadTempR\Document\MyStorage\Help\index.html"
#執行 (請確認執行路徑)
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe /p:Configuration=Debug $SHFB_Root_Path $SHFB_Project_Path
#使用Chrome開啟結果 (請自行調整瀏覽工具)
START Chrome $Result_WebSite
(這裡的警告，是提醒我們，相關註釋沒寫好，記得要去補上)
5. 若想要加 Document 列入版控，可以將其加入類別庫的方案中。
新建 Document 專案後，Documentation Source 滑鼠右鍵 → Add Documentation Source → 找到需要產出文件的 dll 與 xml。
在 Documentation 專案上 → 滑鼠右鍵 → 屬性 (其他步驟跟上面提到的一樣)
結論
目前除了使用 BDD 開發模式，透過完善需求描述、產生 Production Code 的方式；自然地把 Code、文件同時完成。
還有 WebAPI2 的 Help Page, Swagger，也是為了降低串接 API 的溝通問題而產生的解決方案。
透過以上的作法也能快速的產生類別庫文件，提供給同事來使用。
而上述環繞於「動態產生有效的文件」的這個需求，除了因為我們"懶"的再一字一句的打，更希望更自動化的產出有用文件；把節省下來時間，用來開發更好的服務。
最後當我們在開發階段時，記得順手補上相關 summary, parameters , type, returns 等註釋；除了更清楚自己開發的 API 用途，也有助於後續產生「有效文件」。
