RFR: 8292892: Javadoc index descriptions are not deterministic

[Jonathan Gibbons]

On Mon, 29 Aug 2022 21:03:34 GMT, John Neffenger <jgneff at openjdk.org> wrote:

> Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment.

Excellent analysis and write up.

(Just) for the record, I will note there is potentially another case that could be tested, where the element with package access is not exposed until a couple of subtypes down, as compared to being exposed in a direct subtype. That would stress the use of `containingType` in the code.  But the general policy of using and documenting these somewhat hidden elements is all a bit ugly anyway, and I don't know that this extra case appears in JDK.

test/langtools/jdk/javadoc/doclet/testIndexInherited/TestIndexInherited.java line 111:

> 109:     public static void main(String... args) throws Exception {
> 110:         TestIndexInherited tester = new TestIndexInherited();
> 111:         tester.runTests(m -> new Object[]{Path.of(m.getName())});

These days, you can simplify this down to just `tester.runTests();`. The implication of the method will check the signature of the test methods and provide the appropriate path automatically.

test/langtools/jdk/javadoc/doclet/testIndexInherited/TestIndexInherited.java line 154:

> 152:     public void testSuperclass(Path base) {
> 153:         String dir = base.resolve("out").toString();
> 154:         javadoc("-d", dir, "-sourcepath", testSrc, "-private", "pkg1", "pkg2");

At first glance, the use of the `-private` option does not seem to match the method name `testSuperclass` or its matching description (tests entries in the superclass).

There are two characteristics here that seem to be getting mixed up:

1. testing subclasses and superclasses
2. testing with default access (document public and protected) and with "more" access, such as using `-package` or `-private` options.

Ideally, the tests should test subclasses and superclasses with default access, and then repeat, testing subclasses and superclasses with "more" access, such as with `-private`.

test/langtools/jdk/javadoc/doclet/testIndexInherited/pkg1/ClassA.java line 1:

> 1: /*

It's not wrong to use separate files, as you have for `ClassA`, `ClassB` and `ClassC` but generally the prevailing style these days is to generate small test files (like these) from text blocks in the main test file. This makes it easier to see the sources all together, and avoids the overhead of the legal block.  That being said, The amount of text after the legal block puts these in the gray area where either style is OK.

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

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