On Tue, 13 Oct 2020 22:57:25 GMT, Jonathan Gibbons <j...@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
