Generating Javadocs

Javadoc can be generated using the standard mvn javadoc:javadoc command.

  • It can be generated for an individual module:

    cd modules/main/cql
mvn javadoc:javadoc

  • Aggregated javadocs for the entire GeoTools project can be generated using:

    cd modules
mvn javadoc:aggregate

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

Modifying the javadoc configuration

The trunk/pom.xml file contains the javadoc:javadoc goal configuration. This configuration includes hyperlink to external libraries like JTS, list of package to exclude, etc.

Excluded packages are:

  • com.\*

  • org.geotools.maven.\*

  • org.geotools.referencing.util.\*

  • org.geotools.maven.\* * org.geotools.referencing.util.\*

When Maven fails to generate the javadoc

Building Javadoc produces many “warnings” and “errors”. Only errors cause the build to stop. GeoTools javadocs produce a lot of warnings making it difficult to spot the error that caused javadoc to fail.

  1. Thankfully the following Unix command is very helpful:

    mvn javadoc:javadoc | grep "error"

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

  3. In the above example adding the missing </BODY> tag as suggested by the error message would the javadoc generation.