How Do I Document Packages in Java?

Question

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

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

Gareth Davis · Accepted Answer · 2012-10-05T18:00:24.190

281

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

edited Oct 05 '12 at 18:00

answered Mar 08 '09 at 22:42

Gareth Davis

27,701
12
73
106

3

Direct link to spec: http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1 – gavenkoa Oct 05 '12 at 11:57
9

in intellij you can right click on a package and the option to create this should be under the new file menu – bsautner Apr 30 '14 at 17:45
I found the file needed to be in packagename/src/packagename (with the rest of the source files) – trindflo Apr 24 '19 at 19:07

score 56 · Answer 2 · edited Aug 20 '19 at 23:55

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

edited Aug 20 '19 at 23:55

user207421

305,947
44
307
483

answered Mar 08 '09 at 22:42

sleske

81,358
34
189
227

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 '09 at 19:29
3

Update to my previous comment: nowadays IDEA supports `package-info.java` just fine. – Jonik May 28 '13 at 19:38

score 3 · Answer 3 · answered Mar 08 '09 at 22:18

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

answered Mar 08 '09 at 22:18

oxbow_lakes

133,303
56
317
449

2

More details? What should the file look like? – jjnguy Mar 08 '09 at 22:23
1

It's an HTML file containing the description of your package. That's it! – oxbow_lakes Mar 08 '09 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 01 '13 at 16:20

How Do I Document Packages in Java?

3 Answers3

Linked

Related