How can you add a snippet of code in your Javadoc?

Before JEP 413, embedding a code example in Javadoc meant wrapping it in <pre>{@code ... }</pre> and hand-escaping any HTML-sensitive characters in the snippet. It worked, but it was fragile and easy to get wrong for anything beyond a trivial one-liner.

{@snippet} replaces that pattern with a dedicated tag that handles escaping for you and supports both inline snippets and external snippet files.

The simplest form embeds the code directly in the Javadoc comment:

java
/**
 * {@snippet :
 * List<String> names = List.of("Ana", "Bruno");
 * names.forEach(System.out::println);
 * }
 */
void printNames(List<String> names) { ... }

No escaping needed — <, >, and & are written as normal Java syntax.

For longer or reusable examples, you can pull the snippet from an external file using snippet-files, a directory of source files kept alongside your Javadoc sources. Reference a file by name, or a specific region within it using markup comments (@start region=... / @end):

java
/**
 * {@snippet file="Example.java" region="main"}
 */

Tell the javadoc tool where to find these files with the --snippet-path option.

Keeping examples as separate, real source files means they can actually be compiled and tested, so they don't silently rot out of sync with the API they're documenting — a common problem with code embedded as plain text inside comments.

Prefer {@snippet} over the old <pre>{@code}</pre> pattern for any new Javadoc: it's cleaner for inline examples and, via snippet-files and --snippet-path, lets you keep longer examples as verifiable external source files.