Javadoc：package.html 或 package-info.java答案

【问题标题】：Javadoc: package.html or package-info.javaJavadoc：package.html 或 package-info.java
【发布时间】：2011-04-08 08:48:30
【问题描述】：

当尝试创建包级 Javadoc cmets 时，首选方法是什么？你是做什么的？

package-info.java

package.html

对我来说，我一直使用 Package.html。但我想知道它是否是正确的选择。

【问题讨论】：

package-info.java 可以包含 [package] 注释 - 不一定是所有 API 文档。
我不认为 package-info.java 是滥用类。它是一个 java 源文件（具有“.java”文件扩展名）但不是类文件，因为它不包含类声明。而且，事实上，它不能包含类声明，因为“package-info”不是合法的类名。
使用 package-info.java 而不是 package.html 的另一个原因可能是 .java 并不暗示文档的特定输出格式。例如，您可能希望将 javadoc 输出为 LaTeX 或 PDF 文件。根据 javadoc 编译器的实现，这可能会导致 .html 情况下出现问题。
实际上@Scrubbie - 虽然你应该是对的，但我认为你可以在那里指定包私有类。 :-( 不过我同意你的观点，对 Javadoc 和 Annotations 使用 package-info.java 并不是滥用类。
@JonasN 请参阅stackoverflow.com/a/14708381/751579（我知道您在 3 年前就遇到过这个问题，但现在可能其他人需要小费）

【解决方案1】：

package-info.java: "这个文件是 JDK 5.0 中的新文件，优先于 package.html。"—javadoc - The Java API Documentation Generator

附录：最大的区别似乎是包注释。 7.4 Package Declarations 中还有更多的基本原理。

附录：注释功能也提到了here和here。

【讨论】：

首选它的任何特殊原因？
@TheLQ：我猜是包注释，因为编译器有更多信息可以使用；以上。
包注释对我来说是新的，由于它的范围，它似乎是 package-info.java 的一个很好的理由。
编辑答案再多一点：解释“包注释”——将应用于包中的所有类或作为一个整体应用于包的注释。 tech.puredanger.com 链接是唯一真正解释我为什么要关心的链接。也就是说，这是一个很好的有用链接。
使用 package-info.java 您可以使用 {@link } 和其他 doclet。当您链接 java.lang 类时，生成 javadoc 时，您会自动获得指向与您正在使用的 jdk 匹配的类的在线 javadoc 的 {@link }； ide 还可以帮助您在进行重构重构时发现错误的链接。