Javadoc用于项目文档

Question

我想记录我正在处理的Java项目。在过去，我通常会在维基中记录设计和软件API。但是，在最近使用Mockito进行模拟测试后，我对实际javadoc中项目级文档的数量和质量印象深刻。

我的问题是，人们通常使用Javadocs来记录项目的更高级别视图（例如架构，设计决策等），还是这类信息最好记录在（例如）wiki中？

Answer 1

这取决于您的受众群体。

如果您的受众主要使用API​​，通常最好在Javadoc中投入简洁明了的描述（带示例）。如果受众可能永远不会看到API，那么最好在Javadoc之外维护您的文档。这是文档导航方式的主要功能; Javadoc导航有助于编程过程。

至于您是希望将文档放在Wiki还是PDF中，这又取决于受众。如果维基的唯一原因是要有一个面向文档的HTML表示的Web，使用类似于Docbook的东西可能会提供这样的文档，并具有生成相同文档的PDF表示的额外好处。如果你真的有一个活跃的社区，那么wiki可以让近乎陌生的人修改你的文档。

确定产品的优势是否符合您的需求，如果符合您的需求，那么这是正确的选择。

Answer 2

Javadoc非常适合生成API级文档。我使用wiki作为我的高级文档。我使用confluence作为我的wiki，并且有一些插件可用于建筑图。