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

[John Neffenger]

On Mon, 29 Aug 2022 23:19:57 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/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.

I found it useful to have the actual files so that I could prove to myself that this quirk in the Java language is real. I even added a `main` method to `pkg2.ClassC` so that I could run it and see that `ClassC` really does have runtime access to `methodA` with package access in `pkg1.ClassA`.

I also found it useful to have the class files so that I could generate the Javadoc API documentation and look at it myself outside of the test case.

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

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