Codesnippet Javadoc Doclet

Use code snippets in your Java API documentation - on any JDK8+. Fully compatible with snippet support in the latest JDKs. Say farewell to broken or outdated samples in your Javadoc! The Codesnippet Doclet helps you include real code snippets in the documentation ensuring they are always compilable. If you make the samples part of your test suite, even ensuring they execute properly.

Use org.apidesign.javadoc.codesnippet.Doclet to increase quality of your Javadoc now, even when compiling with older JDKs than JDK21 (which is also supported). The doclet uses similar infrastructure as was used when publishing Practical API Design and 20 API Paradoxes books making sure all code samples were correct, compilable and printed with pretty syntax coloring.

This is the documentation for version 0.81 or newer. Read elsewhere about using older or the oldest versions.

How does it work?

The Codesnippet Doclet introduces new tag {@snippet } that allows you to reference real code snippets in your project. Identify the snippets in your code and then reference them from a Javadoc:

/** Snippet demo showing content of {@code main} method:
 *
 * {@snippet file="org/apidesign/javadoc/demo/MainMethodContent.java" region="main"}
 *
 * The snippet is extracted from region {@code main} defined in the
 * {@code MainMethodContent} class below.
 */
public final class MainMethodContent {
    // @start region="main"
    public static void main(String... args) throws Exception {
        System.out.println("Better Javadoc for Everyone!");
    }
    // @end region="main"

    private MainMethodContent() {
    }
}

The rendered Javadoc then looks like:

Identify important pieces of code and add line comment @start: region="samplename" before start of each snippet. Put @end region="samplename" at the end of the code snippet. Then you can reference the snippet in Javadoc with the @snippet tag.

An alternative way is to define inline snippets. Directly embed simple code into the @snippet tag:

/** Snippet demo showing inline snippet. Just type:
 *
 * {@snippet :
 * ClassInlineSnippet snippet = new ClassInlineSnippet();
 * }
 *
 * The previous code instantiates this class.
 */
public final class ClassInlineSnippet {
}

and the snippet renders as

Having correct samples in Javadoc has never been easier!

Use in a Maven Project

The bits of the codesnippet-doclet are being uploaded to Maven central. Add the doclet to your Maven Javadoc plugin configuration (as done here):

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>2.10.3</version>
   <configuration>
     <doclet>org.apidesign.javadoc.codesnippet.Doclet</doclet>
     <docletArtifact>
       <groupId>org.apidesign.javadoc</groupId>
       <artifactId>codesnippet-doclet</artifactId>
       <version>1.0</version> <!-- or any newer version -->
     </docletArtifact>
     <!-- if you want to reference snippets from your test directory, also include -->
     <additionalparam>--snippet-path src/test/java</additionalparam>
    </configuration>
</plugin>

Use in a Gradle Project

Add the doclet to your Gradle javadoc configuration

configurations {
    snippetdoclet
}

dependencies {
    snippetdoclet group: 'org.apidesign.javadoc', name: 'codesnippet-doclet', version: '1.0'
}

javadoc {
    options.doclet = "org.apidesign.javadoc.codesnippet.Doclet"
    options.docletpath = configurations.snippetdoclet.files.asType(List)
    options.addStringOption "snippetpath", "src/test/java"
}

Compatibility with the Latest JDKs

The Codesnippet doclet supports JDK8, JDK11, ..., JDK21. Originally the snippet used slightly different notation to indentify and refer to code snippets. However, since version 0.80 and newer support for standard JDK snippet tags is provided and one can choose whether to support both syntaxes or just the JDK one.

Use -snippetmode jep413 to support just the JDK snippet syntax. This mode allows one to use the Codesnippet doclet on older JDKs and rely on plain javadoc on the latest JDKs. Everything the Codesnippet doclet supports (e.g. @start and @end tags in sources and @snippet tag in Javadoc comments) is fully compatible with the JDK syntax and renders similarly (Codesnippet is better as it automatically adds syntax coloring and links to referenced classes) with both systems.

Use with Command Line Javadoc Tool

Get the Codesnippet Doclet binary. Preferrably from the Maven Central. Invoke your Javadoc as usually plus add following parameters:

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  --snippet-path src/test:src/sample # in case you want to pick the samples from other locations as well

Embed Snippets in API files

You may prefer to include code snippets into the same files as your API to improve life of people who browse the source in an IDE. In such case follow the sample described in EmbeddingSampleCode file - e.g. add yet another class to the end of your file, give it a special name (for example MySnippet) and put code snippet there.

In addition to that you can reference your class as {@link MySnippet} if you pass in additional parameter to specify format of your snippet classes:

$ javadoc \
  -snippetclasses .*Snippet.*

The doclet will then convert all links to classes that match such pattern into appropriate code snippets.

You may want to exclude these sample classes from the final JAR file. The easiest way to do so is to configure your JAR packager to ignore such files:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>2.6</version>
    <configuration>
        <excludes>
            <exclude>**/*Snippet*.class</exclude>
        </excludes>
    </configuration>
</plugin>

Real life example is available here.

Maximum line length

By default Codesnippet will raise an error when the line length of the snippet exceeds 80 characters. This default can be altered by specifying the maximum line length as parameter, like demonstrated below.

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -maxLineLength 120

Verify @since tag

Quality of an API documentation can be increased if one requires that every API element has a @since tag. To verify such statement an automated tool is needed. This doclet is such tool. Just pass verifysincepresent parameter

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -verifysincepresent

and warning will be printed for every element without the @since tag.

Hide @Deprecated Classes

The code snippet doclet can, since version 0.11, exclude Javadoc elements annotated by some annotation from the Javadoc. This is especially useful with java.lang.Deprecated annotation, by using:

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -hiddingannotation java.lang.Deprecated

one can eliminate deprecated fields and methods from the Javadoc and also hide classes and interfaces from the Javadoc overview (however their individual HTML pages still remain in Javadoc for those who keep permanent links to them). One can use the -hiddingannotation parameter with other annotations as well and even repeat the parameter multiple times to hide multiple annotations at once.

Linking types

The doclet searches existing import statements in the code snippet and tries to link the Java files in the package. When a matching type is found, the identifier is wrapped with @link. Note that the linking is best-effort only and when the type is not found, a warning message is logged Tag @link: reference not found: <classname>.

You can suppress the warning by passing the parameter -suppressMissingLinkWarnings as shown below. This parameter will convert the warning to an informational message, so, you can continue to see the types that are missing links and not fail the build on warnings if failOnWarnings flag is set in your javadoc configuration.

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -suppressMissingLinkWarnings

License

Feel free to use the Codesnippet Doclet binary to generate any public or private Javadoc. If you include the Codesnippet Doclet in your product or make modifications to it, please obey its GPL 3.0 license.

Projects Using Codesnippet Doclet

• Truffle in its Javadoc
• Graal in its Graph I/O API
• Apache HTML/Java API in its Javadoc