Document a package using Javadoc

Document a package using Javadoc

Suppose I have a package called com.rgagnon with one HelloWorld class.

com
   rgagnon
        HelloWorld.java

In the directory containing HelloWorld.java, add a file called package.html.

This must be a complete HTML file (with HEAD and BODY). the first line of the body will be used a the package description by javadoc.

<html><head></head><body>
this is <i>com.rgagnon</i> package description, 
see <a href="http://www.rgagnon.com" target="_top">web site</a>
</body></html>

Now execute the javadoc utility located in [JDK]\bin directory from the root of the com.rgagnon package.

\progra~1\Java\jdk1.5.0\bin\javadoc -d javadoc0 -linksource com.rgagnon

where -d javadoc0 is used to specify the output directory and
-linksource to create HTML version of the source file.

See the result.

Since JDK 1.5, to create a package comment file, you have a choice of two files to place your comments:

package-info.java - Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is new in JDK 5.0, and is preferred over package.html.
package.html - Can contain only package comments and Javadoc tags, no package annotations.

See http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment