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

[Jonathan Gibbons]

On Thu, 15 Oct 2020 14:30:54 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> 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`)
>
> 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?

Initially, I put the summary pages in the alphabetic index as well, but it disrupted test files too much. It was
sort-of silly to see `All Classes` and `All Packages` showing up under `A` in the alphabetic index when previously
there was no `A` entry. Hence the change to the current behavior.

See next comment about which category to use.

> 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.

Oops

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

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