package.html vs. package-info.java

Found a good reference¹ on why you should use a package-info.java class.

Notes:

• can contain (package) annotations
• package-info is not a legal identifier for a class². So there's no chance of mistakes from the compiler.
• “It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems.”²
• you're not messing up your source files with .html files, which was in fact the case with the old package.html.

References

[1] Javadoc: package.html or package-info.java

http://stackoverflow.com/questions/3644726/javadoc-package-html-or-package-info-java

[2] The Java™ Language Specification - Java SE 7

http://docs.oracle.com/javase/specs/