RFR: 8345555: Improve layout of search results [v4]
Hannes Wallnöfer
hannesw at openjdk.org
Tue Mar 11 14:37:36 UTC 2025
> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term.
>
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.02/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line.
>
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...
Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:
- Make standalone search page keyboard-friendly
- Merge branch 'master' into javadoc-search
- Review feedback (formatting)
- Remove counterproductive restriction in search pattern
- Fix search menu selecting item at current mouse position
- Rename label property as it has special meaning to jquery-ui
- 8345555: Improve layout of search results
-------------
Changes: https://git.openjdk.org/jdk/pull/23666/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=03
Stats: 799 lines in 26 files changed: 418 ins; 84 del; 297 mod
Patch: https://git.openjdk.org/jdk/pull/23666.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666
PR: https://git.openjdk.org/jdk/pull/23666
More information about the javadoc-dev
mailing list