Added in JDK 18, with JEP 413, the new Code Snippets in Java API Documentation, improves on the experience of embedding code examples in JavaDoc.

JavaDoc Code Examples Pre-JDK 18

Prior to JDK 18, adding code examples to JavaDoc was done with the {@code ...} tag, or for more complex examples, <pre> tags would be used like here. The code contained within a {@code...} however was treated as normal text, and was neither discoverable nor could it be validated for correctness with tools.

JEP 413

JEP 413 defined the new Code Snippets API, which added a new tag; {@snippet ...}. Code contained within {@snippet ...} is discoverable to tools using the Compiler API and Compiler Tree API. This can allow for code snippets to be validated for correctness, though this would be handled by third-party tools and libraries, and not natively by the javadoc tool.

Adding Code Snippets to JavaDoc

Code snippets can be added to JavaDoc in two ways using {@snippet ...}.

In-line Code Snippets

For relatively simple code examples, a code snippet can be added as an in-line element. Within a JavaDoc comment, add {@snippet, a :, new line, and the code example like shown below:

/**
* {@snippet :
	   public void HelloWorld(){
	      System.out.println("Hello World!");
	   }
	}
*/
public void HelloWord(){
	...

Incidental whitespace

Incidental whitespace within a code snippet is handled not too dissimilarly to a Text Block, with whitespace in the columns to the right of the enclosing curly brace “}”, preserved. In the example above, the three whitespace columns would be preserved as padding. However in the example below, there would be no preserved whitespace:

/**
* {@snippet :
		public void HelloWorld(){
			System.out.println("Hello World!");
		}
  		}
*/
public void HelloWord(){
	...

External Code Snippets

Code examples can also be brought in from external files. To reference an external code example, in the {@ snippet add either class, for Java classes, or file, for other file types, attribute, like in the examples below:

{@snippet class="MySnippet"}

{@snippet file="MyProperties.properties"}

Note: Including .java is optional when using the class label and referring to a Java source file.

The external files can be either located in a snippet-files directory that is located in the package of the snippet that is reference the code example, like below:

src
└── mypackage
    ├── MyClass.java
    └── snippet-files
        └── MySnippet.java

Note: The property --source-path must be set for this to work

Or the external files can be located in an arbitrary directory that is then defined by --snippet-path like in this example using the directory name of my-snippets:

src
└── mypackage
    ├── MyClass.java
└── my-snippets
    └── MySnippet.java

 javadoc ... --snippet-path my-snippets

Note: Multiple directories can be defined, just separated by : on *nix systems or ; on Windows.

Regions

Specific regions within a external file can also be referenced using the @start and @end tags and matching on id. Like in this example below using a region called main-method:

public class HelloWorld{
	public static void main(String[] args){// @start region="main-method"
		System.out.println("Hello World!");
	}// @end region="main-method"	
}

/**
* {@snippet class="HelloWorld" region="main-method"}
*/
...

Result:

public static void main(String[] args){
	System.out.println("Hello World!");
}

⚠️ Note: Snippet tags (e.g. // @start and // @end) are inclusive of the lines they are written on, which is why public static void main(String[] args){ is included in the javadoc output.

Additional Tags

There are three additional tags added as part of the Snippet API, for providing additional markup and context to the code examples.

• @highlight - Highlight a segment of code

String myVar = "myValue"; // @highlight substring="myValue"

Result

String myVar = "myValue";

• @replacement - Replace a segment of code

String myVar = "myValue"; // @replacement regex=".*" replacement="..."

Result

String myVar = "...";

• @link - Add a link to text of code

String myVar = "myValue"; // @link substring="String" target="String"

Result

String myVar = "myValue";

⚠️ Links to JavaDoc for the class String

Further Reading

This post only provides a high level overview of the new Snippet API, be sure to checkout the following links for more detail:

• JEP 413: Code Snippets in Java API Documentation
• Programmer’s Guide to Snippets
• The javadoc Command
• Documentation Comment Specification for the Standard Doclet (JDK 18)

Happy coding!