为 java 项目生成 javadoc答案

【问题标题】：Generating javadoc for a java project为 java 项目生成 javadoc
【发布时间】：2011-03-11 11:29:45
【问题描述】：

最近我们计划在我们的项目中使用 checkstyle 插件。作为此练习的一部分，必须清理现有代码以符合 checkstyle 规则。我们发现，接近 18K 的违规对应于类文件中缺少 javadoc cmets。

我的问题是，是否有任何插件或工具可用于为整个工件生成 javadoc cmets？我看了一下 JAutodoc ，我会想知道有没有比这更好的。

【问题讨论】：

【解决方案1】：

即使 CheckStyle 得分上升，生成 JavaDoc 也会降低您的实际代码质量。生成的 JavaDoc 只能反映代码中已经很明显的内容，它增加了体积，降低了可读性，并且它可能（取决于你的工具）不会保持最新状态，增加了维护负担，并在代码发展后导致不一致。

不要让自己陷入混乱的代码中。 CheckStyle 违规应被视为提示，而不是绝对的铁定规则。添加明智的 JavaDoc 需要时间和对代码的理解，您应该制定政策，从现在开始在所有新代码中创建它，并在重构时将其添加到任何现有代码中。

顺便说一句：您不必对所有内容都使用 JavaDoc。我个人不使用 JavDoc 默认的 getter/setter、覆盖或具有不言自明名称的方法/字段（我努力争取）。我总是使用 JavaDoc 顶级实体（接口、类和枚举）并将非 JavaDoc cmets 放在执行复杂操作的代码块上。

【讨论】：

阿德里安，感谢您的回复。就我个人而言，甚至我也有同样的看法。但是我们的客户希望将 javadoc cmets 添加到现有源代码中，并在我们重构代码时对其进行修改。不幸的是，在这种情况下，客户的意见很重要，我们在决策中的发言权较少。

【解决方案2】：

如果您创建了一个 NetBeans 项目，您可以要求它自动为您生成缺少的骨架。在项目上单击鼠标右键以选择菜单项，您将拥有所有缺少的骨架。

另一个工具（花钱，但物有所值）是 Jalopy from triemax 的商业版本，它是一个出色的代码格式化程序（开发人员反应超级灵敏，并在请求时相对快速地添加新功能）。

【讨论】：

【解决方案3】：

最近遇到了同样的问题。我们只是更改了 checkstyle 配置文件，将缺失的 javadocs 设置为仅作为警告，直到我们的贡献者包含缺失的文档。

这里描述了如何做到这一点link text，或者您可以使用提供GUI界面的eclipse checkstyle插件。

【讨论】：

阿里，为代码库手动添加 18000 个 javadoc cmets 看起来像是一项艰巨的任务。我们的计划是现在添加生成的 javadoc，并在我们修改类/方法时对其进行修改。