apache / apache/maven-javadoc-plugin

javadoc with JPMS modules refuses without compiled code

Open
#1,212 6 comments 1 reaction 0 assignees View on GitHub
bug
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.