<分区>
我想记录我正在处理的 Java 项目。过去，我通常在 wiki 中记录设计和软件 API。然而，在最近使用 Mockito 之后对于模拟测试，实际 javadoc 中项目级文档的数量和质量给我留下了深刻的印象。
我的问题是，人们通常使用 Javadoc 来记录项目的更高级别 View (例如架构、设计决策等)，还是这种信息最好记录在(比方说)wiki 中？
<分区>
我想记录我正在处理的 Java 项目。过去，我通常在 wiki 中记录设计和软件 API。然而，在最近使用 Mockito 之后对于模拟测试，实际 javadoc 中项目级文档的数量和质量给我留下了深刻的印象。
我的问题是，人们通常使用 Javadoc 来记录项目的更高级别 View (例如架构、设计决策等)，还是这种信息最好记录在(比方说)wiki 中？
最佳答案
这取决于您的听众是谁。
如果您的受众将主要使用 API，通常最好在您的 Javadoc 中投入清晰简洁的描述(带示例)。如果观众可能永远不会看到 API，那么最好在 Javadoc 之外维护您的文档。这是文档导航方式的主要功能； Javadoc 导航有助于编程过程。
至于您希望将文档放在 wiki 还是 PDF 中，这同样取决于受众。如果 wiki 的唯一原因是拥有面向 Web 的文档的 HTML 表示，则使用类似于 Docbook 的东西可能会为此类文档提供额外的好处，即能够生成相同文档的 PDF 表示。如果您确实拥有一个活跃的社区，那么 wiki 的优势在于允许近乎陌生的人修改您的文档。
确定产品的优势是否符合您的需求，如果符合，那么它就是正确的选择。
关于用于项目文档的 Javadoc，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/6459305/