项目文档的Javadoc

Question

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

我的问题是，人们通常使用Javadocs来记录项目的高层视图（例如架构、设计决策等），还是这种信息最好在维基百科等地方记录？

- Martin

---

这个问题可能更适合 programmers.stackexchange.com。（我投票支持迁移。） - Paŭlo Ebermann

@Paulo 现在我已经注册了programmers.stackexchange.com，我同意这个看法。我投票支持关闭并迁移到programmers.stackexchange.com。 - Martin

Answer 1

这取决于你的受众是谁。

如果你的受众主要会使用 API，那么在 Javadoc 中投资于清晰简明的描述（带有示例）通常更好。如果受众很可能永远不会看到 API，则最好将文档维护在 Javadoc 之外。这主要是由文档导航方式决定的；Javadoc 导航有助于编程过程。

至于是否将文档放在 wiki 或 PDF 中，同样取决于受众。如果 wiki 的唯一原因是拥有面向网络的 HTML 文档表示形式，那么使用类似 Docbook 的东西可能会提供这种文档，并能够生成同一文档的 PDF 表示形式。如果你真的有一个活跃的社区，wiki 在允许陌生人修改你的文档方面非常出色。

确定产品的优势是否与您的需求相符，如果符合，则是正确的选择。

- Edwin Buck

Answer 2

Javadoc非常适合生成API级别的文档。我使用维基来编写高层次的文档。我使用Confluence作为我的维基，有一些插件可以用于架构图。

- telm