Skip to content

Commit

Permalink
Moved documentation from README to project pages.
Browse files Browse the repository at this point in the history
  • Loading branch information
scottfrederick committed May 3, 2010
1 parent 65fac42 commit 24e6434
Showing 1 changed file with 1 addition and 109 deletions.
110 changes: 1 addition & 109 deletions README.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -3,112 +3,4 @@
SpringDoclet is Javadoc doclet that generates documentation on Spring artifacts in a project. The detection of
Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

SpringDoclet currently detects and documents the following types of Spring artifacts:

+ **Components** - classes annotated with @Component, @Controller, @Repository, and @Service
+ **RequestMappings** - classes and methods annotated with @RequestMapping

SpringDoclet writes its output in HTML format into a file named **spring-summary.html**. The location of the file is
determined by the Javadoc "-d" option, with the same defaulting rules as the standard doclet.

## Building SpringDoclet

Before using SpringDoclet, you will need to build it and make it available in your build tool.

To build SpringDoclet, 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.

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

+ 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 Source Xref reports. Classes in the Spring Docs report
are cross-linked to the Source Xref report.
+ 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. 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](http://github.com/scottfrederick/springdoclet/tree/master/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](http://github.com/scottfrederick/springdoclet/tree/master/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.

## ToDos

There are a number of enhancements that will be made to the doclet, including:

+ Support additional Spring artifacts (e.g. @Autowired, @Aspect)

## License

This project is licensed under the terms of the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).

See the [Project Page](http://scottfrederick.github.com/springdoclet) for more information.

0 comments on commit 24e6434

Please sign in to comment.