文檔自動化
— 筆記整理自 北京理工大學 計算機學院
文檔自動化
- 文檔很重要!
- 軟件開發人員不愛寫文檔
- 軟件的使用和維護必需文檔
- 多餘的文檔對客戶和開發人員都是一種負擔
- 不愛寫文檔 -> 沒人讀 -> 文檔過時
- 文檔自動化的優勢
- 簡化項目文檔生成過程
- 維持精確性、一致性和時效性
- 減輕開發人員負擔
設計文檔
- 在早期的軟件開發過程中，設計和編碼是分開的
- 不同的人員使用不同開發工具，程序員編碼時很容易偏離設計
- 現在很多IDE廠商如：vs 在其中植入了多工種平臺，架構師，設計師，程序員可以在同一個IDE中進行工作
- 從類圖到代碼，從UML模型到html文檔, 再加上版本控制工具，不同工種之間的協作更加流暢了
- Together的代碼和類圖實現雙向同步功能，讓文檔的編寫和生成不再是痛苦的事情
LiveSource TM 技術
- 雙向同步功能的建模工具是讓人興奮的事情，之間是單項工具，畫好類圖後進行生成，比較雞肋。
- Together的LiveSource TM 技術實現了時時雙向同步技術
代碼逆向UML圖
- 設計階段的UML圖與代碼不一致
- 構建時自動生成UML圖
- 從本質上來說UML本身也是一種非常重要的文檔
- 示例:UMLGraph工具
- UMLGraph和javadoc生成了html格式的UML類圖
- 具體做法是：在註解腳本中把代碼中想提取的一些javadoc註釋的屬性傳入，生成和代碼一致的UML類圖
- 這些操作可以封裝在腳本里, 自動的跑起來，每次構建都會得到最新的文檔並自動發佈到開發團隊的內部網站上去
數據庫文檔化
- 絕大多數軟件系統都採用數據庫來存儲數據
- 數據庫的設計和管理需要採用很專業的技能
- 數據庫設計工具ERWin正向設計流程
- 設計好ER圖
- 通過ERWin等工具畫出邏輯視圖和物理視圖
- 確定實體之間的關係
- 確定主鍵、外鍵、字段屬性等等
- 這些工具可直接連接數據庫
- 將物理視圖轉化爲DBL代碼, 並在數據庫中執行
- 同時可導出各類數據詞典文件, 作爲數據庫設計的文檔
- 這些操作很方便，也很強大
- 這裏依然存在文檔生成的方向性問題
- 程序員在編程過程中需要修改數據庫的某個表,字段，如何維持一致性
- 手工維護工作量巨大，不能保證完全的一致性
數據庫文檔化示例
- 從數據庫中抽取所需的元素生成數據庫文檔
- 這個方案是衆多方案中的一個，比較靈活
- 結合SchemaSpy, Ant 和 javadoc 最後生成了html格式的數據庫文檔
- 配置焦恩可以配置到持續集成的過程中，每次編譯後是最新的
備註：圖片託管於github，請確保網絡的可訪問性
代碼文檔化示例
- 代碼的局部說明
- 行註釋//…
- 塊註釋/…/
- Javadoc註釋 /** …*/
- Xml註釋 ///
- API文檔可以更全面瞭解代碼
- 通過Javadoc，Ndoc， Doxgen等文檔工具可以將註釋和相關代碼提取出來，進一步處理爲易於閱讀的外部文檔htm，doc，pdf等
用戶文檔示例
- 最頭疼的是用戶文檔，大部分時間都浪費在文檔的複製粘貼上，對文檔的排版更是麻煩
- 結合使用 Ant、一個 DocBook XSL 文件和 XSL Formatting Objects (XSL-FO) 來生成 PDF 格式的用戶文檔
備註：圖片託管於github，請確保網絡的可訪問性