原文はこちら。
The original article was written by Dustin Marx.
https://marxsoftware.blogspot.com/2021/09/jdk-18-code-snippets-in-java-api.html

OpenJDK 18早期アクセスビルド 16（訳注：2021/10/14現在の早期アクセスビルドの最新は18）が利用可能になっています。これにはJDK 18での導入をターゲットとしているJEP 413: Code Snippets in Java API Documentationの実装が含まれています。

JDK 18 Early-Access Builds
https://jdk.java.net/18/
JEP 413: Code Snippets in Java API Documentation
https://openjdk.java.net/jeps/413
JEP proposed to target JDK 18: 413: Code Snippets in Java API Documentation
https://mail.openjdk.java.net/pipermail/jdk-dev/2021-September/005989.html

このJEPは、「@snippet タグをJavaDocの標準Docletに導入し、サンプルソースコードをAPIドキュメントに簡単に含めることができるようにする」ことを目的としており、このJEP自体がJavadoc {@snippet} タグがサポートする構文と機能をカバーしています。

JEP 413には以下のような記述があります。

JEP 413 では、Javadocの新たなタグ {@snippet } を導入します。

We introduce a new inline tag, {@snippet ...}, to declare code fragments to appear in the generated documentation. It can be used to declare both inline snippets, where the code fragment is included within the tag itself, and external snippets, where the code fragment is read from a separate source file.（新たなインラインタグ {@snippet ...} を導入し、コードフラグメントを宣言して生成されたドキュメントに現れるようにします。このタグを使うと、コードフラグメントがタグ自身の中に含まれるようなインラインスニペットと、コードフラグメントが別のソースファイルから読まれる外部スニペットの両方を宣言できます）

The @snippet tag – https://openjdk.java.net/jeps/413#The-@snippet-tag

このJEPには、{@snippet }がサポートするものおよびその構文について詳細の記載があります。このエントリでは{@snippet }がJavadocベースのドキュメントに何をもたらすのかをちょいとだけご紹介します。このエントリのコードはGitHubからご利用いただけます。

dustinmarx/javademos
https://github.com/dustinmarx/javademos/tree/master/src/dustin/examples/jdk18/javadoc

このいかにも感のあるコードでは、{@snippet }を使っています。

package dustin.examples.jdk18.javadoc;

/**
 * Demonstrates {@code @snippet} Javadoc tag targeted for JDK
 * as part of JEP 413 (AKA Bug JDK-8201533):
 * <ul>
 *     <li>https://openjdk.java.net/jeps/413</li>
 *     <li>https://bugs.openjdk.java.net/browse/JDK-8201533</li>
 * </ul>
 *
 * An instance of this class is obtained via my {@link #newInstance()} method
 * rather than via a constructor.
 *
 * {@snippet :
 *    final SnippetExample instance = SnippetExample.newInstance(); // @highlight substring="newInstance"
 *    instance.processIt();
 * }
 */
public class SnippetExample
{
    /**
     * No-arguments constructor not intended for public use.
     * Use {@link #newInstance()} instead to get an instance of me:
     * {@snippet :
     *    final SnippetExample instance = SnippetExample.newInstance();   // @highlight substring="newInstance"
     * }
     */
    private SnippetExample()
    {
    }

    /**
     * Preferred approach for obtaining an instance of me.
     *
     * @return Instance of me.
     */
    public SnippetExample newInstance()
    {
        return new SnippetExample();
    }

    /**
     * Performs valuable processing.
     */
    public void processIt()
    {
    }
}

上記コードをjavadoc toolを使って -private オプションを使って実行すると、クラスと引数なしのコンストラクタのコードスニペットをHTMLに生成します。生成されたHTMLでは、ハイライトされた部分が太く強調されていることにも注意してください。

JavaDoc Tool
https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html#GUID-7A344353-3BBF-45C4-8B28-15025DDCC643

パッケージのドキュメントで特に {@snippet }が有用な場所だと思うのが、パッケージの説明文です。パッケージの説明に使用するコードの例は、以下の package-info.java のコードリストにあります。

/**
 * Examples and demonstrations of Javadoc-related capabilities.
 *
 * The main entrypoint for the snippets example is the {@link SnippetExample} class:
 * {@snippet :
 *    final SnippetExample instance = SnippetExample.newInstance();  // @highlight substring="SnippetExample" @link substring="SnippetExample.newInstance()" target="SnippetExample#newInstance()"
 * }
 */
package dustin.examples.jdk18.javadoc;

生成されたHTML出力のパッケージレベルのドキュメントは以下のようです。

Javadocベースのドキュメントにコードスニペットを含める上での課題の一つが、生成されたHTMLではなく、ソースを直接見た場合に、コード表示のために使用されるタグ（<pre>、<code>、{@code} など）のためにJavadocのコメントが読みづらくなってしまう、ということでした。{@snippet } のような Javadocタグだと、生成されたHTMLではコードの表示を良くしつつも、ソースコード自体ではあまり注意をそらせるようなことがなくなります。JEP413では、Javadocにコードスニペットを含めるための現在のアプローチの欠点を取り上げ、{@snippet }がそれらの欠点にどのように対処するかをまとめています。

A better way to address all these concerns is to provide a new tag with metadata that allows the author to implicitly or explicitly specify the kind of the content so that it can be validated and presented in an appropriate manner. It would also be useful to allow fragments to be placed in separate files that can be directly manipulated by the author’s preferred editor.（このような問題に対処するためには、新しいタグにメタデータを付与して、コンテンツの種類を作者が暗黙的または明示的に指定できるようにすることで、コンテンツを適切な方法で検証して表示できるようにするのがよいでしょう。また、フラグメントを別のファイルに配置できるようにして、著者の好みのエディタで直接操作できるようにすることも有用と思われます）

Motivation – https://openjdk.java.net/jeps/413#Motivation

JEP 413には、外部ファイルに含まれるコードの参照が可能が可能という例も含め、{@snippet }の適用例が多数あります。