apache / apache/maven-javadoc-plugin
Code Snippets (JEP 413, Java 18) are not supported
- Dominant language
- Java
- Stars
- 107
- Forks
- 116
- Avg merge
- 1d 10h
- Merged PRs (30d)
- 16
Description
### Affected version
3.11.2
### Bug description
[JEP 413: Code Snippets in Java API Documentation](https://openjdk.org/jeps/413), 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:
```xml
*.snippet-files.*
```
### Notes
There are [other configuration profiles that try to compile & run snippet files](https://nipafx.dev/javadoc-snippets-maven/). The long-term solution might be more convoluted than the `excludePackageNames` one-liner I shared above.
Contributor guide
No contributing guide indexed for this repository
Research direction
Reproduce the failure with the minimal pom.xml and src/main/java/foo example, then compare the Maven Javadoc Plugin invocation with the direct javadoc command. Trace how the plugin discovers packages under snippet-files and verify that JEP 413 sources are handled without requiring the excludePackageNames workaround.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- build-system
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100