RFR: JDK-8253559: The INDEX page should link to Serialized Form and Constant Values pages [v2]

[Hannes Wallnöfer]

On Tue, 13 Oct 2020 22:57:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> The mechanism to add links for summary pages in the main index is generalized, and now includes the Constant Values
>> page, the Deprecated page and the Serialized Form page, provided these pages have non-empty content.
>> The only change to the generated output is very minor: the text of existing link to the "System Properties" page is
>> changed to use a non-breaking space, in line with the links for "All Classes" and "All Packages".
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove redundant field
>   (There is an equivalent field in `HtmlDocletWriter`)

I'm surprised the mechanism to add links to the top of the index page can be generalized with so few changes.

I think this change needs to be checked and possibly tuned for the changes it causes to the search index contents.
Basically we need to make sure these summary pages show up in the search results in the correct places (categories).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2662:

> 2660:      * The entries may come from the AST and DocCommentParser, or may be autromatically
> 2661:      * generated comments for mandated elements and JavaFX properties.
> 2662:      ** @see CommentUtils#dcInfoMap

I think you unintentionally removed a line break while fixing the reference.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java line 169:

> 167:             // don't put summary-page items in the A-Z index:
> 168:             // they are listed separately, at the top of the index page
> 169:             itemsByFirstChar.computeIfAbsent(keyCharacter(item.getLabel()),

You're preventing these summary pages from showing up in the alphabetic index, but not from the by-category index
below. This means they are added to the javadoc search contents, which by itself is a good thing. However, this means
we also need to think about the category under which the item is listed. For example, you are using
`IndexItem.Category.MEMBER` for the Deprecated API list, but deprecation applies to all element categories. I guess we
should use the `TAGS` category for summary pages unless there is a clear element category they fit in?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java line 308:

> 306:             configuration.mainIndex.add(IndexItem.of(IndexItem.Category.MEMBERS,
> 307:                     resources.getText("doclet.Deprecated_API"), path));
> 308:         }

`IndexItem.Category.MEMBERS` is probably not the correct category to use for the Deprecated API page, and we should
choose a fitting category because these summary page items will end up in the search index (see my comment in
`IndexItem#add`)

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

PR: https://git.openjdk.java.net/jdk/pull/643