jax-doclets

jax-doclets is an open-source project maintained by Lunatech Labs.

Here is an example of documented JAX-RS and JAXB code:

package com.lunatech.doclets.jax.test;

import javax.ws.rs.*;
import javax.xml.bind.annotation.*;

/**
 * An example JAX-RS resource
 */
@Path("/example")
@Produces( { "application/xml", "application/*+xml" })
public class JAXRSExample {

  /**
   * An example resource
   */
  @XmlRootElement
  public static class JAXBExample {

    /**
     * The resource ID
     */
    @XmlID
    @XmlElement
    String id;

    /**
     * The example contents
     */
    @XmlValue
    String contents;

    /**
     * An optional attribute
     */
    @XmlAttribute
    String type;
  }

  /**
   * Gets an example resource
   * 
   * @param id
   *          the example id
   * @param type
   *          the type of resource we prefer
   * @param startIndex
   *          the start index
   * @return an example resource suitable for the given parameters
   * @HTTP 404 if there is no such example resource
   * @RequestHeader X-Example-Auth the authentication header
   * @ResponseHeader Location a pointer to the example details
   */
  @Path("{id}")
  @GET
  public JAXBExample getExample(@PathParam("id") String id, 
                                @MatrixParam("type") String type, 
                                @QueryParam("start") int startIndex) {
    return new JAXBExample();
  }
}
  

Figure 1.2. Result of documented JAX-RS code

Figure 1.3. Result of documented JAXB code

JavaDoc is read either on the JAX-RS resource methods, or their interface. Only method-level JavaDoc is used. Documentation for a given RESTful URL is taken from the method annotated with @GET, @HEAD, @POST, @PUT or @DELETE for that URL (in order of preference).

JAX-RS resource locators are supported.

Since the JAX-RS supports links to JAXB documentation, you should first run the JAXB doclet, then the JAX-RS doclet using the -link parameter.

The following standard JavaDoc tags are supported on resource methods:

The following specific JavaDoc tags are supported on resource methods:

The following standard JAX-RS annotations are supported on resource methods or classes:

The following RESTEasy annotations are supported on resource methods or classes:

JavaDoc is read either on the JAXB properties (getter methods or fields), or their interface (only for the getters) as well as on the JAXB classes.

Since the JAX-RS supports links to JAXB documentation, you should first run the JAXB doclet, then the JAX-RS doclet using the -link parameter.

There are no standard JavaDoc tags supported. Everything comes from JavaDoc comments.

There are no specific JavaDoc tags supported.

The following standard JAXB annotations are supported on properties or classes:

The following Java types have a special mapping in XML:

Any other type is taken to be either a Java type or a JAXB type, for whom proper links will be generated.