RFR: 8292892: Javadoc index descriptions are not deterministic [v2]

[John Neffenger]

On Mon, 29 Aug 2022 23:26:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> John Neffenger has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Rename test class members and rewrite its comments
>
> 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`.
> 
> ... the point being, that we should not see the replicative behavior when documenting with `-private`, should we? The elements with package access should be documented in their defining class, right?

Right. I renamed most of the members and methods of the test class and rewrote its comments, which were far too terse. I also added a check that the inherited members do not show up in the index when they're already listed for the declaring superclass. I think it's much better now, but let me know what you think.

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

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