[jdk19] RFR: JDK-8288058: Broken links on constant-values page

[Jonathan Gibbons]

On Mon, 27 Jun 2022 14:40:32 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> JDK 19:
>> 
>> Please review a medium-simple fix for some broken links on the constant-values page, from the "contents" index at the top of the page to the summary tables lower down on the page.
>> 
>> There are two root causes:
>> 
>> The packages are grouped into "groups" with headings based on abbreviated package names, meaning "at most two leading components of each package name". At one point there is a probable typo, when a full package name is used instead of the abbreviated name, thus causing the wrong "id" to be generated, thus causing broken links. The fix for this is obvious: use the correct name.
>> 
>> More seriously, the abbreviated package name is modeled using a PackageElement. While seemingly a good idea, the construction of these elements inherits the module element of the originating package. Then, the package elements are used to build a `Set` of headings, based on these package elements. The problem is that when the subpackages are found in different modules, they give rise to distinct "abbreviated package elements" in different modules and thus cause repeated instances of like-named headers in the output. This is easily visible as repeated headers for com.sun.* in (for example) the [JDK 18 API](https://docs.oracle.com/en/java/javase/18/docs/api/constant-values.html). The fix is to use a Set<String> to model the set of headers and associated links, instead of Set<PackageElement>.
>> 
>> Along with the two fixes described above, there is minor code cleanup, including the removal of some ill-considered code in both Workarounds and Utils. Apart from those classes, the changes are confined to the "constant summary" builder and writers. The use of a member called "first" and related shenanigans is a holdover from the days when the page was generated literally top-to-bottom with print statements. It is easily removed.
>> 
>> The only existing test for the constant values page was laughably insufficient, and was effectively just a regression test for a minor issue in JDK 1.4.2. The test is enhanced with a bunch of new test cases, that exercise different scenarios for the list of contents at the top of the page, and the links to the corresponding sections lower down. The new test cases leverage the implicit support for checking links in the generated output, although they do forcibly enable that support, just to make sure it is active.
>> 
>> When comparing the new JDK API docs against recent JDK API docs, the only changes are the expected changes in the links and headings on the constant-values.html page.
>> 
>> There is more cleanup that could be done to this page ... such as suppressing the "contents:" list when it is just a single entry ... but that is an enhancement that is out of scope for this bug fix.
>
> test/langtools/jdk/javadoc/doclet/testConstantValuesPage/TestConstantValuesPage.java line 93:
> 
>> 91:                     """,
>> 92:                 """
>> 93:                     package p2;
> 
> Does the test expect the `p2` package NOT to appear in the "contents" list because `p2` is not mentioned in the javadoc command?

yes, the constants page should only include the "included packages" given on the command line.  Note the test verifies a complete list on lines 112-115, so is a positive verification of the absence of `p2`.

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

PR: https://git.openjdk.org/jdk19/pull/62