On Thu, 19 Oct 2023 16:03:37 GMT, Pavel Rappo <prappo at openjdk.org> wrote:
> Please review this fix to a bug in indexing.
>
> The bug has been dormant for many releases and was noticed only because its likelihood was increased by [JDK-8286470](https://bugs.openjdk.org/browse/JDK-8286470) in JDK 21.
>
> Here's the bug: every time an item is indexed, it is indexed relative to the context that triggers the indexing. For example, if an item is indexed in the context of a class page, then the index will refer to that class page. However, if that same item is indexed in the context of the "Deprecated" page, then the index will refer to the "Deprecated" page.
>
> Since an item is indexed every time it is seen, the fix is to never index an item if seen in the context of a _derived_ page, such as hierarchy trees, indexes, and various lists (e.g. deprecated, new, preview). The fix includes a comprehensive test and updates an existing test to correct its bad assumptions.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1374:
> 1372: if (node.getName().toString().matches("(?i)h[1-6]")
> 1373: && !(HtmlDocletWriter.this instanceof IndexWriter)
> 1374: && !(HtmlDocletWriter.this instanceof SummaryListWriter<?>)) {
Should we add a `Writer` method to identify primary/derived/secondary writers such as `isPrimaryWriter()` or `isDerivedWriter()`? The `instanceof` check with these two classes looks a bit fragile and untidy.
test/langtools/jdk/javadoc/doclet/testIndex/TestSelfIndexing.java line 153:
> 151: "package-use.html", "package-tree.html", "preview-list.html",
> 152: "new-list.html", "allclasses-index.html", "allpackages-index.html",
> 153: "constant-values.html", "system-properties.html", "serialized-form.html"
The hard-coded list of derived HTML files could become outdated when new lists are added. For example, we just recently added `restricted-list.html` for restricted methods. Could we detect this from the presence of a dash in the file name, as this is our way to avoid conflict of derived files with Java types?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/16271#discussion_r1365862146
PR Review Comment: https://git.openjdk.org/jdk/pull/16271#discussion_r1365870157