Javadoc: package.html or package-info.java
When trying to create package level Javadoc comments, whats the preferred method? What do you do?
package-info.java
- Pros
- Newer
- Cons
- Abuse of a class - Classes are for开发者_如何学编程 code, not for only comments
package.html
- Pros
- HTML extension means its not code
- Syntax highlighting in IDE's/text editors
- Cons
- None?
For me, I've always used Package.html. But I'm wondering if its the correct choice.
package-info.java
: "This file is new in JDK 5.0, and is preferred over package.html."—javadoc - The Java API Documentation Generator
Addendum: The big difference seems to be package annotations. There's a little more in the way of rationale in 7.4 Package Declarations.
Addendum: The annotation feature is also mentioned here and in Javadoc tip: Prefer package-info to package.html, cited here.
Addendum: See also What’s package-info.java
for?.
精彩评论