Added by Martin Desruisseaux, last edited by Martin Desruisseaux on May 05, 2007  (view change) show comment

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Javadoc can be generated using the standard mvn javadoc:javadoc command. It can be generated for an individual module, by invoking mvn javadoc:javadoc in this specific module, or for the whole Geotools project, by invoking mvn javadoc:javadoc from the root. The latter is called aggregated javadoc.

Dependencies in aggregated javadoc

As of October 2006, aggregated javadoc using maven-javadoc-plugin version 2.0 fails to resolve all external dependencies like JTS or GeoAPI. It may be related to MJAVADOC-66, but the later said that the bug is already fixed. Waiting for the next maven-javadoc-plugin release in the hope that it will be fixed there.

JAR files for distribution

JAR files are created by invoking mvn javadoc:jar after mvn javadoc:javadoc. They are created in the target directory for each module.

Custom javadoc tags

Geotools code contains a few custom javadoc tags, including:

Tag Purpose Example
@source The file URL, usually provided by SVN itself. @source $URL$
@tutorial Link a tutorial page on this server.  

Those custom tags are processed by taglets provided in the Geotools maven/javadoc module. Those taglets are automatically used by the javadoc tools when using the javadoc:javadoc goal.

Modifying the javadoc configuration

The gt/pom.xml file contains the javadoc:javadoc goal configuration. Configuration includes custom taglets, hyperlink to external libraries like JTS, list of package to exclude, etc. Excluded packages are com.*, org.geotools.maven.* and org.geotools.resources.*.

When Maven fails to generate the javadoc

Javadoc has "warnings" and "errors". Only errors cause the build to stop. Unfortunatly our javadoc in Geotools is not in very good shape, since it causes a lot of warnings to be generated. It is difficult to spot the little fatal error that caused javadoc to fail in the middle of hundreds of warnings. Thankfully the following Unix command is very helpful:

mvn javadoc:javadoc | grep "error"

The above gives a much smaller output, typically only about 5 lines. So we can spot immediately the cause of javadoc failure, for example something like:

modules/library/referencing/src/main/java/org/geotools/referencing/factory/epsg/package.html:
error - Close body tag missing from HTML file

In this particular example, adding the missing </BODY> tag as suggested by the error message fix the javadoc generation. It is that simple.