用於項目文檔的Javadoc

Question

我想記錄正在處理的Java項目。在過去，我通常在wiki中記錄設計和軟件API。然而，在最近使用Mockito進行模擬測試後，我對實際javadoc中項目級文檔的數量和質量印象深刻。

我的問題是，人們通常使用Javadocs來記錄項目的更高級別的視圖（例如架構，設計決策等），還是這種信息最好記錄在一個wiki中？

Answer 1

這取決於你的觀衆是誰。

如果您的受衆將主要使用API​​，那麼在您的Javadoc中投入清晰簡潔的描述（帶有示例）通常會更好。如果觀衆可能永遠看不到該API，那麼最好在Javadoc之外維護文檔。這主要是文檔如何導航的功能; Javadoc導航有助於編程過程。

至於是否希望將文檔放在wiki或PDF中，這又取決於觀衆。如果維基的唯一原因是有文件的面向網HTML表示，使用類似的Docbook的東西可能會提供這些文件與生成相同的文檔的PDF交涉能力的好處。如果你真的擁有一個活躍的社區，wiki能夠讓接近陌生的人修改你的文檔。

確定產品的優勢是否符合您的需求，如果他們這樣做，那麼這是正確的選擇。

Answer 2

Javadoc非常適合生成API級文檔。我爲我的高級文檔使用維基。我使用confluence作爲我的wiki，並且有幾個插件可用於架構圖。