Javadoc：package.html 或 package-info.java

当尝试创建包级 Javadoc 注释时，首选方法是什么？你做什么工作？

包信息.java

• Pros
  • Newer
• Cons
  • 滥用类 - 类用于代码，而不仅仅是注释

包.html

• Pros
  • HTML 扩展意味着它不是代码
  • IDE/文本编辑器中的语法突出显示
• Cons
  • None?

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

package-info.java：“这个文件是 JDK 5.0 中的新文件，并且优先于 package.html。”—javadoc - Java API 文档生成器 https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#packagecomment

附录：最大的区别似乎是包注释。还有更多的理由7.4 包声明 https://docs.oracle.com/javase/specs/jls/se8/html/jls-7.html#jls-7.4.

附录：还提到了注释功能here http://tech.puredanger.com/2007/02/28/package-annotations/ and in Javadoc 提示：优先选择 package-info 而不是 package.html https://web.archive.org/web/20080204050234/http://blogs.sun.com/darcy/entry/javadoc_tip_prefer_package_info, cited here https://github.com/jddarcy/BlogsSunComArchive#2006.

附录：另见What’s package-info.java for? https://www.intertech.com/Blog/whats-package-info-java-for/.