Code Snippets (JEP 413, Java 18) are not supported

[vy]

Affected version

3.11.2

Bug description

JEP 413: Code Snippets in Java API Documentation, delivered in Java 18, introduces an @snippet tag for JavaDoc's Standard Doclet, to simplify the inclusion of example source code in API documentation. This feature is not supported by Maven JavaDoc Plugin and requires extra configuration. Ideally, this should just work out of the box.

Reproduction

$ cat pom.xml
# Nothing of interest, semantically empty

$ tree src
src
└── main
    └── java
        └── foo
            ├── Foo.java
            └── snippet-files
                └── bar
                    └── Bar.java

$ cat src/main/java/foo/Foo.java 
package foo;
/// {@snippet class="bar.Bar"}
public class Foo {}

$ cat src/main/java/foo/snippet-files/bar/Bar.java 
package bar;
public class Bar {}

$ javadoc -d target/reports/apidocs --source-path src/main/java
# Works as expected

$ mvn -V javadoc:javadoc
...
Apache Maven 3.9.8 (36645f6c9b5079805ea5009217e36f2cffd34256)
Maven home: /home/vy/.m2/wrapper/dists/apache-maven-3.9.8/af622e91
Java version: 24.0.1, vendor: Oracle Corporation, runtime: /home/vy/Downloads/jdk-24.0.1
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-60-generic", arch: "amd64", family: "unix"
...
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.11.2:javadoc (default-cli) on project maven-sandbox: An error has occurred in Javadoc report generation: 
[ERROR] Exit code: 2
[ERROR] error: Illegal package name: "foo.snippet-files.bar"
[ERROR] 1 error
[ERROR] Command line was: /home/vy/Downloads/jdk-24.0.1/bin/javadoc -J-Duser.language= -J-Duser.country= @options @packages

Workaround

As a workaround, one can configure maven-javadoc-plugin to exclude snippet-files folders:

<configuration>
    <excludePackageNames>*.snippet-files.*</excludePackageNames>
</configuration>

Notes

There are other configuration profiles that try to compile & run snippet files. The long-term solution might be more convoluted than the excludePackageNames one-liner I shared above.

[michael-o]

Should they really be part of the Java code? This looks wrong.

[michael-o]

I don't consider this as a bug, but as a new feature. It only emerged after the plugin has been developed.

[vy]

Should they really be part of the Java code? This looks wrong.

@michael-o, quoting from the JEP:

... the file can be placed in a package hierarchy rooted in a snippet-files subdirectory of the directory containing the source code with the {@snippet ...} tag. Alternatively, the file can be placed on an auxiliary search path, specified by the --snippet-path option to the javadoc tool.

I don't know where snippets should be placed, though javadoc by default looks at the snippet-files folder residing next to the source code with the @snippet tag.

I don't consider this as a bug, but as a new feature. It only emerged after the plugin has been developed.

Fair enough. 👍

[michael-o]

Should they really be part of the Java code? This looks wrong.

@michael-o, quoting from the JEP:

... the file can be placed in a package hierarchy rooted in a snippet-files subdirectory of the directory containing the source code with the {@snippet ...} tag. Alternatively, the file can be placed on an auxiliary search path, specified by the --snippet-path option to the javadoc tool.

I don't know where snippets should be placed, though javadoc by default looks at the snippet-files folder residing next to the source code with the @snippet tag.

I don't consider this as a bug, but as a new feature. It only emerged after the plugin has been developed.

Fair enough. 👍

Wait a second, if this is placed with the source code can't Javadoc pick it up by itself?

[vy]

Wait a second, if this is placed with the source code can't Javadoc pick it up by itself?

Yes, javadoc works as expected – I've updated the Reproduction section in the ticket description.