javadoc with JPMS modules refuses without compiled code

[homberghp]

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 runmvn 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

/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

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

[desruisseaux]

It is not helpful for the present case, but just for information: improving JPMS support with Javadoc is also planed for Maven 4. I did not had the time to work on Javadoc yet, but it is on my list of plugins that I wish to upgrade. The current status are:

• Maven Compiler plugin 4.x (~90% done, pending 2 pull requests)
• Maven Resource plugin 4.x (~50% done)
• Maven Surefire plugin (~5%)
• Maven JAR (0%)
• Maven Javadoc (0%)

I realize that it does not help for the current issue, this is just for info.

[homberghp]

could I somehow help?
I may have some time available.

[desruisseaux]

The first step would to reach an agreement on the strategy. Currently, Maven Compiler Plugin and Maven Javadoc plugin are two independent plugins. I would like to merge the Javadoc plugin into the compiler plugin for reasons explained below. However, I suspect that it may be a controversial proposition which would meet resistance on the mailing list. So I was delaying that argument for later.

The reasons why I would like to have the Javadoc being generated directly by the Maven compiler plugin is because the two javac and javadoc tools share a lot of the same API, namely javax.tools. The former is controlled by the JavaCompiler interface while the latter is controlled by the DocumentationTool interface, but both of them take the same arguments, in particular: JavaFileManager, JavaFileObjects and DiagnosticListener. Setting those objects is not easy, especially in a JPMS context, and this work is already done by the Maven Compiler plugin. It would be much easier, and probably more efficient (because of caches), to opportunistically reuse those objects for Javadoc generation as we have them at hand than recreating them again in the Maven Javadoc plugin. I think that it would also be easier for users because many configuration parameters for Maven Compiler and Maven Javadoc plugins are the same (encoding, Java version, etc.)

We can also see the fact that javac and javadoc are closely related in the javac -Xdoclint options, which uses the javadoc tools right at compilation time for verifying that the Javadoc is well formed.

So in short, actually I do not really have a plan to update the Maven Javadoc plugin. My plan is rather to have an option in the version 4.x of the Maven Compiler plugin for opportunistically generating the Javadoc. But I know that it would be a controversial proposal, so I keep the debate for latter. However, if a volunteer is willing to make this experiment now, it could be a branch of the compiler plugin. It would give us a proof of concept for discussion on the mailing list.

[homberghp]

Your approach sound reasonable and pragmatic, so I would agree with that.

I could even imagine that a future version of compiler and javadoc plugin use a common component or dependency that maximizes the benefits of your approach, yet still support two plugins, each with potentially different configuration parameters.

Where do I start?

[desruisseaux]

You can clone the master branch of https://github.com/apache/maven-compiler-plugin/. In the ToolExecutor class, between lines 599 and 607, the compilation tasks are created and executed. The work would be:

• Get a DocumentationTool instance in addition of JavaCompiler if documentation is enabled.
• Create a DocumentationTask in pretty much the same way as a CompilationTask is created, with pretty much the same arguments except configuration.options.

The javadoc would probably needs its own configuration.options, but these options would also have a lot in common with the current compiler options. For example, I don't think that it make sense to have a source file encoding option for the compiler and a separated source file encoding option for documentation. It should be the same encoding. Same argument for source file version, etc. I would suggest to start by not introducing any new configuration option (except an option for enabling javadoc) and only pickup whatever existing option is relevant to Javadoc. We could see in a second phase what to do about the javadoc-specific options.

The block of code loops over CompilationTaskSources instances. I would need to check for being sure, but if I remember right, this is for multi-releases support: the code iterates first for the base --release version, then iterates for next --release versions. I don't thing that it makes senses for Javadoc. So, the javadoc tools should probably be executed only in the first iteration and do nothing in all subsequent iteration. We would need to check if the iteration is for other purposes than multi-releases, I do not remember right now.