Como adicionar um trecho de código no seu Javadoc?

Antes da JEP 413, embutir um exemplo de código no Javadoc significava envolvê-lo em <pre>{@code ... }</pre> e escapar à mão qualquer caractere sensível a HTML dentro do trecho. Funcionava, mas era frágil e fácil de errar em qualquer coisa além de uma linha trivial.

{@snippet} substitui esse padrão por uma tag dedicada que cuida do escaping pra você e suporta tanto trechos inline quanto arquivos externos de snippet.

A forma mais simples embute o código diretamente no comentário Javadoc:

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

Nenhum escaping necessário — <, > e & são escritos como sintaxe Java normal.

Para exemplos mais longos ou reutilizáveis, você pode puxar o trecho de um arquivo externo usando snippet-files, um diretório de arquivos-fonte mantido junto com as fontes do seu Javadoc. Referencie um arquivo pelo nome, ou uma região específica dele usando comentários de marcação (@start region=... / @end):

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

Informe à ferramenta javadoc onde encontrar esses arquivos com a opção --snippet-path.

Manter os exemplos como arquivos-fonte reais e separados significa que eles podem de fato ser compilados e testados, então não apodrecem silenciosamente fora de sincronia com a API que documentam — um problema comum com código embutido como texto simples dentro de comentários.

Prefira {@snippet} ao velho padrão <pre>{@code}</pre> em qualquer Javadoc novo: é mais limpo para exemplos inline e, via snippet-files e --snippet-path, permite manter exemplos mais longos como arquivos-fonte externos e verificáveis.