Javadoc用于项目文档

Question

我想记录我正在研究的Java项目.在过去,我通常会在维基中记录设计和软件API.然而,在最近使用Mockito进行模拟测试之后,我对实际javadoc中项目级文档的数量和质量印象深刻.

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

Answer 1

这取决于您的观众是谁.

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

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

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