235

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.

Robert
  • 39,162
  • 17
  • 99
  • 152
TheLQ
  • 14,830
  • 14
  • 69
  • 107
  • 48
    `package-info.java` can contain [package] annotations - it's not necessarily all API docs. – Tom Hawtin - tackline Sep 05 '10 at 02: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. – Scrubbie Dec 28 '11 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. – honeyp0t Jul 13 '12 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. – mjaggard Sep 27 '12 at 10:22
  • Unfortunately, in Eclipse, I can't find a way to bring up the Javadoc view for a package-info.java I made... :( There seems to be nothing that can be recognized as the 'thing' that the Javadoc is attached to. – Jonas N Nov 07 '12 at 16:24
  • 2
    @JonasN see http://stackoverflow.com/a/14708381/751579 (I know you had this problem 3 years ago, but maybe someone else needs the tip now) – davidbak Nov 20 '15 at 22:45
  • Package-info.java contents appear on Eclipse in a small window when we pass the mouse over each package name. eg: {{ package org.test.jobs.timecontrol }}. A different contents will appear for each word. – Jose Tepedino Apr 07 '19 at 15:48

1 Answers1

275

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

trashgod
  • 203,806
  • 29
  • 246
  • 1,045
  • 3
    Any particular reason why its preferred? – TheLQ Sep 05 '10 at 02:24
  • 2
    @TheLQ: I'm guessing package annotations, as the compiler has more information to work with; more above. – trashgod Sep 05 '10 at 02:49
  • 3
    Package annotations are new to me, and seem a good reason for package-info.java due to its scope. – stacker Sep 05 '10 at 02:55
  • 6
    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. – Roboprog Jul 11 '12 at 21:29
  • 6
    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. – Luigi R. Viggiano May 23 '13 at 17:13
  • 1
    You can also apply package metadata like JaxB's @XmlSchema with package-info.java. – Lakatos Gyula Oct 02 '15 at 08:23