239

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.

Improve this question
7
  • 48
    package-info.java can contain [package] annotations - it's not necessarily all API docs. Commented Sep 5, 2010 at 2:12
  • 57
    I wouldn't qualify package-info.java as an abuse of a class. It's a java source file (has a ".java" file extension) but is not a class file because it does not contain a class declaration. And, in fact, it can not contain a class declaration because "package-info" is not a legal class name. Commented Dec 28, 2011 at 18:45
  • 21
    Another reason for using package-info.java instead of package.html could be that .java does not imply a specific output format of the documentation. For example you might want to output the javadoc as LaTeX or as a PDF file. Depending of javadoc compiler implementation this could cause problems in the .html case. Commented Jul 13, 2012 at 12:06
  • 3
    Actually @Scrubbie - although you should be right, I think you can specify package-private classes in there. :-( I agree with your sentiment though, using package-info.java for Javadoc and Annotations is not an abuse of a class. Commented Sep 27, 2012 at 10:22
  • 2
    @JonasN see stackoverflow.com/a/14708381/751579 (I know you had this problem 3 years ago, but maybe someone else needs the tip now) Commented Nov 20, 2015 at 22:45

1 Answer 1

Reset to default
280

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?.

Improve this answer
Sign up to request clarification or add additional context in comments.

6 Comments

Any particular reason why its preferred?
@TheLQ: I'm guessing package annotations, as the compiler has more information to work with; more above.
Package annotations are new to me, and seem a good reason for package-info.java due to its scope.
Edit answer just a bit more: explain "package annotation" -- an annotation which is to be applied to all of the classes in a package or otherwise to the packages as a whole. The tech.puredanger.com link was the only one to really explain why I should care. That said, it's a good, helpful link.
using package-info.java you can use {@link } and other doclets. When you link a java.lang class, when javadoc is generated you automatically get the {@link } pointing to the online javadoc of the class matching the jdk you are using; ide can also help to spot wrong links when you do refactoring refactoring.
|

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.