• Home
• News
• Open-Source
• About

• Overview
• jax-doclets

jax-doclets

jax-doclets v0.7

About

jax-doclets allows you to generate JavaDoc documentation for specific Java annotation-based extensions such as:

• JAX-RS: the RESTful API for Java
• JAXB: the XML binding API for Java

This is done by implementing a custom doclet for each API which is then used by the traditional javadoc command to generate the documentation.

In the future we will be adding support for at least the following APIs:

• JPA: the Object Relational Model API for Java
• Hibernate Search: a full-text indexing API for Java
• Bean Validation: the validation API for Java

Examples

You can see the JavaDoc files generated by our doclets on example APIs:

• JAX-RS API documentation
• JAXB API documentation

Usage

Once you have downloaded our doclets jar, simply use the following ant task:

 <path id="compile.classpath">
  <pathelement location=".../jax-doclets-0.7.jar"/>
 </path>

 <target name="jax-doc-jaxrs" description="Generate JAX-RS documentation">
  <javadoc classpathref="compile.classpath" sourcepath="${src.dir}"
           destdir="${build.dir}/jaxrsdocs/" extdirs="${lib.dir}"
           doclet="com.lunatech.doclets.jax.jaxrs.JAXRSDoclet"
           docletpathref="compile.classpath">
   <link href="../jaxbdocs/"/>
  </javadoc>
 </target>
	
 <target name="jax-doc-jaxb" description="Generate JAXB documentation">
  <javadoc classpathref="compile.classpath" sourcepath="${src.dir}"
           destdir="${build.dir}/jaxbdocs/" extdirs="${lib.dir}"
           doclet="com.lunatech.doclets.jax.jaxb.JAXBDoclet"
           docletpathref="compile.classpath">
  </javadoc>
 </target>

Here's an example of JavaDoc for JAX-RS:

/**
 * This is our order resource
 */
@Path("/order")
@Produces("application/xml")
public class Order {

 /**
  * Gets a single order
  * @param orderKey the order key
  * @return the order if found
  * @HTTP 404 order not found
  */
 @GET
 @Path("{id}")
 public Order getOrder(@PathParam("id") String orderKey){…}

 /**
  * Gets every order
  * @return every order
  * @returnWrapped com.foo.OrderList
  */
 @GET
 public Response getOrders(){…}

 /**
  * Uploads an order
  * @param order the order to upload
  * @inputWrapped com.foo.Order
  */
 @POST
 public void postOrder(String orderAsString){…}

}

Documentation

All documentation is available in the following formats:

• HTML single page
• HTML one page per chapter
• PDF

Download

You can download everything over on our Google Code project page.

Source code

Our source code repository is browsable on our Google Code project page.

Bugs

Expect many, since this is pre-release quality.

In particular, the standard doclet options are not all used (most of them aren’t to be honest).

We will soon have a bug report tool available.

Versions

0.7

• Fixed -footer parameter
• Added JS client API example for JAX-RS doclet
• Added JSON example for JAXB doclet
• Use @GET, @HEAD, @POST, @PUT, @DELETE methods for resource documentation in this order

0.6

• Custom stylesheet support
• Aligned CSS class names with JavaDoc class names
• Added resource index page for JAX-RS
• Default to UTF-8 encoding
• Added intra-links and anchors to JAX-RS methods and JAXB categories
• Support RESTEasy's @Form annotation
• Added deep-links in JAX-RS overview for empty resources

0.5

• Wrote a manual
• Layout tweaks
• Support -charset, -footer and -header parameters (Peter Bryant)
• Moved path parameters to top of documentation (Peter Bryant)
• Added -jaxrscontext parameter (Peter Bryant)
• Added @RequestHeader and @ResponseHeader taglets (Peter Bryant)

0.4

• Support resource locators and sub-resources
• Support methods with no @Path annotation

0.3

• Marked JAXB collections in the JavaDoc
• Turned @HTTP output into a list
• Added support for multiple @returnWrapped

0.2

• Added support for @return JavaDoc and generate output documentation
• Added taglet "@inputWrapped className" so that we can specify the real type of an input parameter of type String
• Added taglet "@returnWrapped className" so that we can specify the real type of a return value of type String or Response
• Support old versions of @Consumes and @Produces (@ConsumeMime and @ProduceMime)