Use code snippets in your Java API documentation - in any JDK8+. Fully compatible with forthcoming snippet support in JDK18. 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 JDK18. 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.

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!

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>0.81</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>

Add the doclet to your Gradle javadoc configuration

configurations {
    snippetdoclet
}

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

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

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

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

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

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.

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

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.

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.

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

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.

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