apache / apache/maven-javadoc-plugin
javadoc with JPMS modules refuses without compiled code
- Dominant language
- Java
- Stars
- 107
- Forks
- 116
- Avg merge
- 1d 10h
- Merged PRs (30d)
- 16
Description
### Affected version
3.11.3-SNAPSHOT
### Bug description
Since JPMS, and finding a module-info.java path inside the source directories, mvn javadoc:javadoc insist that the compiles code should be compiled first, or at least it gives a warning to that effect.
However, the JDK javadoc tool when used on the command line, has no such requirement. This is odd.
Also non-JMPS projects do not show this behaviour.
To show the effect, take a JPMS project, add the debug parameter to the javadoc-plugin setup
and run`mvn clean javadoc:javadoc`.
Then run `mvn clean compile javadoc:javadoc`, which works as expected.
The debug flag set earlier leaves the command line instrumentation in the target/reports/apidocs directory.
* `javadoc.sh` the generated script with used files
* `options` this contains workdir specific values
* `packages` sic
* `@argfile` which specifies the module name
The script contains a call to the JDK command line tool, in my case
```shell
/usr/lib/jvm/jdk-21.0.7+6/bin/javadoc -J-Duser.language= -J-Duser.country= @options @packages @argfile
```
The options file specifies the output directory equivalent to the standard place for the produced apidoc.
Copy these files to the basedir for instance (linux) with
```shell
cp target/reports/apidocs/{javadoc.sh,options,packages,argfile} .
```
Now you are set for the experiment
First clean `mvn clean`
Then `./javadoc.sh` inside the basedir.
This shows that the JDK javadoc tool does NOT require the code to be compiled.
Example project:
[JavadocTest.zip](https://github.com/user-attachments/files/21016868/JavadocTest.zip)
Contributor guide
No contributing guide indexed for this repository
Research direction
Reproduce the behavior in a JPMS example with `mvn clean javadoc:javadoc`, then compare it with `mvn clean compile javadoc:javadoc`. Inspect the generated files under `target/reports/apidocs`, especially `javadoc.sh`, `options`, `packages`, and `argfile`, and run the copied script after cleaning. Done means Javadoc succeeds without compiled code or an equivalent unnecessary warning.
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
- 35/100