RFR: JDK-8322865: JavaDoc fails on aggregator modules

[Hannes Wallnöfer]

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)

Looks good, with one potential issue found in the test.

test/langtools/jdk/javadoc/doclet/testModules/TestAggregatorModule.java line 91:

> 89: 
> 90:         out.println("Checking for error message");
> 91:         if (outputLines.stream().anyMatch(l -> l.contains("No public classes"))) {

Minor: the JBS issue suggests the error message was "error: No public or protected classes found to document", which would not match this check.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17272#pullrequestreview-1850774393
PR Review Comment: https://git.openjdk.org/jdk/pull/17272#discussion_r1470938203