Using JCite With JavaDoc

JCite can be used within java doc comments using the {.jcite …}@ tag. While you could also just embed the standard JCite markup in your doc comments, using the JavaDoc tag has a number of benefits:

No need for a second, separate processing pass for the HTML files generated by JavaDoc.

No need for specifying the package name of the class you’re citing from if it’s in the same package as the class you’re citing into.

Note: You have to set up JavaDoc before you can use the {@.jcite ...} tag.

The JCite Tag
Setting Up JavaDoc

The JCite Tag

Using JCite in JavaDoc is very similar to using it in standalone documents. You simply write {@.jcite ...} instead of the standard tag. Here’s an example:

/**
 * Returns the addend which was passed to the constructor. As in:
 * {@.jcite ch.arrenbrecht.jcite.examples.AdderTest:-- getAddend}
 *
 * @return the addend.
 */

which cites a snippet from the class AdderTest:

public void testGetAddend() throws Exception
{
  // -- getAddend
  Adder one = new Adder( 1 );
  int addend = one.getAddend();
  assertEquals( 1, addend );
  // -- getAddend
}

The output looks like this (getAddend method).

The {@.jcite ...} tag is a JavaDoc inline tag. This means you can embed it within sentences. In the output, the cited source is still inserted as a pre tag, meaning it is properly shown in a paragraph of its own. This is so you can use it everywhere, including method parameter and exception documentation.

It seems, though, that a method comment like

/**
 * Does something. {@.jcite -- example}
 */

will cause the example code to be included in the class’s method overview. JavaDoc does not properly recognize the end of the first sentence. To fix this, you have to use something like:

/**
 * Does something. Example: {@.jcite -- example}
 */

Citing From The Same Package

When citing from source classes that are in the same package as the one you are documenting, you can omit the package name in the {@.jcite ...} tag:

/**
 * Class that adds a specific value to other values. Typical usage: {@.jcite AdderTest:-- useCase}
 *
 * Note how we can omit the package specification of the target class if it resides in the same
 * package as this class. If the class is in another package, we have to specify it:
 * {@.jcite ch.arrenbrecht.jcite.examples.otherpackage.SomethingElse:-- fromOtherPackage}
 *
 * @author peo
 */

This relies on the fact that the AdderTest, while in a separate source folder, is still in the same package as the class under test, Adder. (So, yes, we could have omitted the package name in the first example too.) If the cited class is in another package, we do have to give the package, though (as shown above, too).

The output looks like this.

Citing From The Same Class

When citing from the very class you are documenting (for example, parts of the implementation of a method), you can omit the source class in the {@.jcite ...} tag too. This is shown in the example below in the documentation of the parameters (which also shows that you can insert citations into parameter documentation):

/**
 * Adds two numbers. Example: {@.jcite AdderTest:-- add}
 *
 * Note how, in the parameter documentation, we can cite from the current class's source
 * directly, that is, omitting the target class part.
 *
 * @param a first addend, as in {@.jcite -- add; highlight a; strip b}
 * @param b second addend, as in {@.jcite -- add; highlight b; strip a}
 */
public static int add( int a, int b )
{
  // -- add
  return /*a*/a/*a*/ + /*b*/b/*b*/;
  // -- add
}

The standard tag documentation explains the use of highlighting and other features of JCite’s citation markup.

The output looks like this.

Setting Up JavaDoc

Before you can use the {@.jcite ...} tag, you have to configure JavaDoc so it knows where to find JCite. In addition to your own startup options, you have to provide the following:

javadoc
  -tagletpath ...(all jars from lib/ and build/)...
  -taglet ch.arrenbrecht.jcite.JCiteTaglet
  ...

where for -tagletpath you have to specify all the jars found in JCite’s lib/ and build/ folders, separated by ; (Windows) or : (Unix).

This tells JavaDoc to load the JCite taglet (a JavaDoc plugin), which supports the {@.jcite ...} tag.

Source Path

In this configuration, you can only cite from the sources that you are running JavaDoc on, i.e., those found in the path given in the standard JavaDoc option sourcePath:

javadoc
  ...
  -sourcepath <pathToSourceBeingDocumented>
  ...

Typically you want to cite source code from special unit tests (which I call example tests) that showcase your API and are annotated with comments indicating what to cite. These usually are not on the JavaDoc sourcePath. To tell JCite where to find them, you have to specify an additional option to JavaDoc (which, in fact, sets a system property for the Java VM – I found no other way to pass in information):

javadoc
  ...
  -J-Djcitesourcepath=<pathToAddlSourceCitedFrom>
  ...

Verbosity

To make the JCite taglet report citations, use:

javadoc
  ...
  -J-Djciteverbose=true
  ...

Style Sheet

Finally, since JCite emits HTML that relies on CSS for formatting, you should specify a stylesheet for JavaDoc’s output. If you already have one, integrate the JCite-specific instructions into it. Otherwise you may want to use JCite’s default stylesheet. In any case, you need to tell JavaDoc to use it:

javadoc
  ...
  -stylesheetfile <stylesheet.css>
  ...

Complete Example

Here’s a complete example which I use to produce the test documentation for JCite’s JavaDoc integration:

javadoc
  -tagletpath ...(all jars from lib/ and build/)...
  -taglet ch.arrenbrecht.jcite.JCiteTaglet
  -public
  -sourcepath src/examples
  -J-Djcitesourcepath=src/test
  -J-Djciteverbose=true
  -d temp
  -stylesheetfile src/test/data/style.css
  -overview src/examples/overview.html
  ch.arrenbrecht.jcite.examples