Custom Javadoc Tags

Miredot uses default Javadoc and JAX-RS annotations to document the interfaces. As such, the @param and @throws tags are used to document the parameters and exceptions of the method. Some additional tags exist that allow you to add extra spice to your documentation.

@summary or @title

@summary or @title is intended as a one sentence summary of the functionality of the interface, and is used as the title in the documentation.

For example:

/**
 * This is the large documentation of the interface. It states that the interface
 * cleans cars, but does so quickly, safely and very cheaply. It also causes red
 * cars to become blue.
 * @summary Cleans the given car
 */

See also title naming

@servicetag

A service tag is simply a label you attach to your interface. There are several use cases for this tag. One might add labels to indicate a certain semantic category to which the interface belongs (for example, you could label each interface related to products in your store with @servicetag product.

Another use case would be to document the implementation status of a certain interface or as an indicator on whether or not the interface is public or private. Any number of service tag tags are permitted per method, tags associated with an interface class are applied to all methods belonging to that class. An example:

/**
 * @servicetag car
 */
@Path("/rest/car/")
public interface CarService {

    /**
     * @servicetag geo
     * @param location The id of the car whose location is to be retrieved
     * @returns the location fo the car
     */
    @GET
    @Path("{carId}/location")
    @Produces("application/json")
    Location getLocation(@PathParam("carId") Long location);
}

The above sample marks the interface to retrieve information of a car with the label car whereas the interface to retrieve the location of the car is labeled with both car and geo.

@statuscode

If a method returns a specific HTTP status code, you can document this with the custom @statuscode tag as shown below. After the tagname, put the status code followed by a space and the comment you wish to use for documentation in the interface.

/**
 * @statuscode 412 If any of the input parameters are invalid.
 */

Another way to use the @statuscode tag is to use an enum class as parameter (before the status code) instead of a message.

/**
 * @statuscode my.package.UserMessageCode 412
 */

If an enumeration class is used, the statuscode tag is "duplicated" for each value in the enumeration. The message for each statuscode is created from the toString() method of the enumeration class.

The example enumeration class example above would be visualized (for example) as:

• 412 MyFirstEnumValueAsToString
• 412 MySecondEnumValueAsToString
• 412 MyThirdEnumValueAsToString

If an enumeration class and a message are both present in the @statuscode tag, the enumeration class will be ignored.

See status codes for a detailed explanation on other ways to add status codes to your docs.

@responseheader

If you set outgoing headers in your response you can document them with the @responseheader tag as shown below. After the tagname, put the name of the header followed by a space and the comment you wish to use for documentation in the interface.

/**
 * @responseheader Warning A warning that gets set as a side effect.
 */