210

In the Java APIs I can see Javadoc comments for packages.

How/where do I place Javadoc comments to document a package?

3 Answers 3

284

As of 1.5 you can define a package-info.java file and provide a standard javadoc style comment for a package:

com/foo/package-info.java:

/**
 * com.foo is a group of bar utils for operating on foo things.
 */
package com.foo;

//rest of the file is empty

Language specification for packages

3
56

Up to and including Java 1.4, you had to provide a HTML file package.html, as described in the other answers.

Since Java 1.5 you can also provide a package-info.java, which contains a regular Javadoc comment (no HTML). The latter is preferred, as it gives you some extra features (notably package annotations).

Details: Sun's docs for javadoc

2
  • 2
    +1 for mentioning both ways, and the essential difference between them. By the way, at least IntelliJ IDEA currently has better support for package.html (Ctrl-Q on a package name shows the package Javadocs).
    – Jonik
    Mar 23, 2009 at 19:29
  • 3
    Update to my previous comment: nowadays IDEA supports package-info.java just fine.
    – Jonik
    May 28, 2013 at 19:38
3

With a package.html file at the package level (i.e. in the directory for that package). This should be a fully-formed HTML file, with the <html> tag defined in it

3
  • 2
    More details? What should the file look like?
    – jjnguy
    Mar 8, 2009 at 22:23
  • 1
    It's an HTML file containing the description of your package. That's it! Mar 8, 2009 at 22:25
  • 6
    This is the old way to do it. From Java 1.5 onwards you can use package-info.java
    – k2col
    Nov 1, 2013 at 16:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.