Integrated: JDK-8322865: JavaDoc fails on aggregator modules

[Jonathan Gibbons]

On Thu, 4 Jan 2024 21:27:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a simple fix that JavaDoc fails when asked to just generate documentation for an aggegator module, or for any module that contains no classes or interfaces to be documented, such as a service-provider module.
> 
> The problem is the long-standing check for `no public or protected classes found to document`.  While that check does have an exception for "empty" modules, such modules are not taken into account when specified as a `module-info.java` file on the command line. (The workaround is to specify the source path and use the `--module` option.)
> 
> The fundamental part of the fix is in `ElementsTable.scanSpecifiedItems`, where code is added to scan any compilation units read from files specified on the command line, detect any module declarations, and add any corresponding module names to the list of `specifiedModuleElements`.
> 
> A secondary part of the fix is purely cosmetic. The misleadingly-named `classTrees` and `classTreeList` are renamed to `compilationUnits` and `compilationUnitList` to better reflect their broader use, including the possibility of containing a module compilation unit.
> 
> A new test is added, in two variants.
> 
> 1. The first variant is a regular call of `JavadocTester.javadoc`. In this call, the source path has to be set explicitly, to avoid the default setting of the source path performed by the `javadoc` method.  (The exact setting of the source path is significant to `javac` when determining module-membership of command-line source files.)
> 
> 2. The second variant used `toolbox.JavadocTask` to avoid setting the source path in any way, thus better mimicking the initial test case of `javadoc -d path/to/api path/to/src/module-info.java`
> 
> Both variants pass, but then trigger a downstream error of a circularity in the redirection in the generated `index.html` file. That issue is addressed separately, in [JDK-8322874](https://bugs.openjdk.org/browse/JDK-8322874)

This pull request has now been integrated.

Changeset: 482c1006
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/482c10064668d8309873173b1773ca406883fda3
Stats:     130 lines in 3 files changed: 119 ins; 1 del; 10 mod

8322865: JavaDoc fails on aggregator modules

Reviewed-by: hannesw

-------------

PR: https://git.openjdk.org/jdk/pull/17272