文檔生成 - 我應該打勾什麼框？

Question

我正在尋求要求我的團隊爲一些即將到來的重大項目更徹底地記錄他們的代碼，並讓生活不那麼痛苦，我轉向了XML文檔生成器，例如Sandcastle，Doxygen或Box Live Documenter。

在評估最佳選項時，我應該記住的關鍵考慮因素是什麼，以及有哪些經驗促使您做出特定決定？

Answer 1

對我來說，關鍵因素是：

1. 全自動：可不可以以這樣的方式，使相當多 沒有外出工作需要 創建或編輯的文檔設置。

2. 完全風格：可以在文檔完全樣式所以 它產生之後，它在維基或pdf 看起來不錯。我應該 能夠改變顏色，字體大小， 佈局等

3. 良好的過濾：我只能選擇我想成爲產生 的項目。我應該能夠 過濾器的命名空間，文件類型， 類等

4. 定製：我可以包括頁眉，頁腳，自定義元素， 等

我發現的Doxygen可以做到這一切。我們的工作流程如下：

1. 開發者進行了更改代碼

2. 他們更新權利，他們只是改變了

3. 上面的代碼的文檔標籤，我們點擊生成按鈕

Doxygen將從代碼中提取所有XML文檔，將其過濾爲僅包含我們想要的類和方法，以及應用我們預先爲其製作的CSS樣式。我們最終的結果是一個內部wiki，它看起來是我們想要的，並且不需要編輯。

額外：我們有我們所有的項目在各種git倉庫。我們將所有這些拉到一個根文件夾，並生成此根文件夾的文檔..

有興趣知道其他人如何進一步自動化..？

Answer 2

1. 誰在爲文檔付費？爲什麼？ （系統是否足夠穩定，是否增加了足夠的價值）
2. 誰將閱讀它，爲什麼她沒有使用更有效的溝通渠道？ （如果正確的話，主要是時間/地點的距離）
3. 誰會保持它的最新狀態。
4. 你什麼時候要摧毀它？ （自動，如果它沒有被閱讀或在過去三個月更新一次？）

我大多喜歡更好的代碼，使我的生活痛苦少，在更多的文檔，但我喜歡的場景&單元測試和高高層架構描述。

文檔耗費時間和金錢編寫並保持最新。 JavaDoc樣式文檔對可同時顯示的代碼量有嚴重的不利影響，對於使用代碼的開發人員來說可能是一個好主意，但對於那些編寫代碼的人來說可能不是。