apache / apache/maven-javadoc-plugin

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

Open
#1,206 5 comments 0 reactions 0 assignees View on GitHub
enhancement priority:major
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.