SpringDoclet

Download this project as a .zip file Download this project as a tar.gz file

Downloading SpringDoclet

You can download pre-built binaries of SpringDoclet as a jar file. For each pre-built version of SpringDoclet there are two jar files. The springdoclet-<version>.jar file contains just the compiled code for the SpringDoclet itself. The springdoclet-<version>-jar-with-dependencies.jar file contains SpringDoclet along with all libraries needed by the doclet.

Building SpringDoclet

To build SpringDoclet from source, you will need to either download the code from GitHub as a zip or tar file, or clone the GitHub repository.

After downloading the code, use Maven from the root directory of the project.

To build the doclet and deploy it to a local Maven repository, use "mvn install".
To build the doclet and package it as a jar file (for use with Ant, the command line, etc), use "mvn assembly:assembly". This will create a single .jar file in the "target" directory of the project. The .jar file contains the SpringDoclet classes and all dependent libraries.

Testing SpringDoclet

After building the doclet, you can test it with either Maven or Ant in the "sample" directory in the project.

Testing with Maven

To test the doclet with Maven, navigate to the "sample" directory and run "mvn site". This should generate standard Maven site output in the "sample/target/site" directory. The "Project Reports" section of the generated site should have a link to a Spring Docs report along with JavaDocs and ource Xref reports. Classes in the Spring Docs report are cross-linked to the Source Xref report.

Testing with Ant

To test the doclet with Ant, navigate to the "sample" directory and run "ant build". This should create directories under "sample/target" containing standard Javadoc output and SpringDoclet output.

Using SpringDoclet

To use SpringDoclet, simply instruct the Javadoc tool to use this doclet instead of (or in addition to) the standard doclet. The Javadoc tool needs to be provided with:

the name of the doclet class (org.springdoclet.SpringDoclet)
the jar file containing the doclet classes

In addition to the doclet classes, Javadoc needs access to the class files that implement the annotation types used to detect Spring artifacts (e.g. @Controller, @RequestMapping). Make sure the necessary Spring jar files are in the classpath used to run the Javadoc tool. If any annotation types cannot be located by Javadoc, SpringDoclet will display an message like this in the Javadoc output:

Unable to resolve annotation type '@Controller'; to fix this problem,
add the class that implements the annotation type to the javadoc classpath

This message will be shown for all annotations found in the Java source but not found on the classpath. It can be ignored for all non-Spring annotations.

This doclet is implemented in the Groovy programming language. If you built or downloaded the jar-with-dependencies then only the SpringDoclet jar file needs to be in the Javadoc classpath. If you built or downloaded the jar without dependencies then Javadoc will also need the Groovy runtime (e.g. groovy-1.7.2.jar) in its classpath to execute the SpringDoclet.

Options

SpringDoclet supports the following options to control its operation:

-d directory
Specifies the output directory for the generated documentation. Defaults to the current directory.
-f filename
Specifies the name of the output file for the generated documentation. Defaults to "spring-summary.html".
-stylesheet path
Specifies the path to a stylesheet CSS file. This can be a relative or absolute path. By default, SpringDoclet creates its own stylesheet file named "spring-summary.css" in the same directory as the generated documentation.
-linkpath path
Specifies the path to documentation for source code files (i.e. JavaDoc or JXR xref files). This should be set to the root of the directory containing the source code documentation HTML files. Defaults to the current directory.

SpringDoclet with Maven

Follow the instructions in the Maven Javadoc plugin documentation to configure SpringDoclet as an alternate doclet:

http://maven.apache.org/plugins/maven-javadoc-plugin/examples/alternate-doclet.html

An example of using SpringDoclet with Maven is also included in the project. See the pom.xml file in the sample directory.

When using SpringDoclet with the Maven Javadoc plugin, the generated Maven site HTML will assume there is a file named index.html in the output directory. You can use the "-f" option to override the default output file name to "index.html" for compatibility with Maven site generation.

SpringDoclet with Ant

Refer to the Ant Javadoc task documentation to configure SpringDoclet as an alternate doclet:

http://ant.apache.org/manual/CoreTasks/javadoc.html

An example of using SpringDoclet with Ant is also included in the project. See the build.xml file in the sample directory.

SpringDoclet with the command line

Use the "-doclet" and "-docletpath" parameters to the Javadoc command-line tool to use SpringDoclet instead of the standard doclet. Refer to the JDK documentation for more details.