創建/維護C++項目文檔的最有名的方法？

Question

但在這裏它關心我幾點：

• 你如何保持文檔 將被髮布給客戶？
• 如何處理內部使用的文檔？
• 如何記錄包/類/方法/ API？
• 如何確保可維護性？例如簽入標準，代碼審查清單項目，自動化。

Answer 1

doxygen是一個很好的文檔工具。它可能可以覆蓋您的大部分需求。就客戶文檔和內部文檔而言，我只考慮給客戶提供界面類和文檔。實現細節應該被認爲是內部的，並且在單獨記錄的源文件中。

Answer 2

一般; 指定 it，設計 it，build it。這種抽象層次將使所有文檔任務變得更簡單，並且文檔錯誤既更明顯，也更不重要。如果你建立它，然後追溯記錄它，你會喜歡麻煩。這將是一項艱鉅的工作，根本無法完成，細節層面不太適合需要文檔的不同受衆（例如最終用戶，開發人員和維護人員）。此外，你的經理或其他項目發起人不會知道你正在建設什麼，直到它完成，並且像這樣黑暗這不是一件好事。

• 您如何維護將向客戶發佈的文檔？

大部分可以（也應該）從產品需求規格生成並沒有多大的代碼（除非也許你是賣一個庫，而不是應用程序）。這具有可以與開發同時生成的優點。

• 怎麼樣的內部使用文檔？

用於技術說明的MS Word。 UML爲我打算建立，Doxygen爲什麼實際上被修造。希望兩者之間有一些對應關係，但UML模型代表開發者和維護者的路線圖，而Doxygen輸出是細節。儘管一些工具的「往返」工程能力在理論上確保代碼和文檔（或者更確切地說型號）被同步，但是充分詳細描述UML模型以允許直接生成代碼通常是低效的。

通常，我會添加獨立的Doxygen標記文件，其中包含未在代碼標記中表達的高級文檔，具體說明單個界面如何一起使用。這可能包括代碼示例，時序圖，HTML和外部文檔的鏈接。

• 如何記錄包/類/方法/ API？

Doxygen的

• 如何保證維修？例如簽入標準，代碼審查清單項目，自動化。

當然，這是真正的問題！？其他人只是關於工具。例如，Doxygen會針對缺失或不一致的參數文件和其他不一致或遺漏發出警告。我將Doxygen代作爲自動生成步驟加入，並將它的警告視爲編譯器錯誤。在團隊環境中，您可以使用持續集成工具來執行此操作，並在開發人員簽入代碼時通知開發人員，這些代碼不會構建沒有警告的文檔。