RFR: JDK-8248863: Add search landing page to API documentation

[Jonathan Gibbons]

On Wed, 13 Apr 2022 16:01:17 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> This is the second of two PRs to enhance JavaDoc search, it is based on the first one (#8185).
> 
> It adds a standalone search page (search.html) along with its own script file (search-page.js). This PR is very similar to the last prototype I uploaded and demoed, the changes are mostly tweaks to the markup, style sheets and text. 
> 
> JDK API docs rendered with this patch can be viewed and tested here (top-level files only):
> http://cr.openjdk.java.net/~hannesw/8248863/api.01/

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 318:

> 316:                 DocPaths.JQUERY_UI_JS.getPath(),
> 317:                 DocPaths.JQUERY_UI_CSS.getPath(),
> 318:                 "jquery-ui.structure.min.css",

Should this be a constant name as well?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java line 43:

> 41: 
> 42: /**
> 43:  *  Generate the search landing page for the generated API documentation.

Just one space between `*` and `Generate`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java line 48:

> 46:  *  If you write code that depends on this, you do so at your own risk.
> 47:  *  This code and its internal interfaces are subject to change or
> 48:  *  deletion without notice.</b>

We don't use these lines any more

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java line 55:

> 53:      * Constructor to construct SearchWriter object.
> 54:      * @param configuration the configuration
> 55:      * @param filename File to be generated.

minor: lower case "file" and no final period.

consider using IDE to reformat/align the param info

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java line 63:

> 61: 
> 62:     /**
> 63:      * Construct the SearchWriter object and then use it to generate the search

OK, for new comments, you really should use the -s form ;-)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java line 108:

> 106:         }
> 107: 
> 108:         contentTree.add(HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,

Wow, 40 lines of fluent API calls!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search-page.js line 241:

> 239:             resultSection.hide();
> 240:         } else {
> 241:             notify.html("Searching...");

hmmm, should this be localized?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 688:

> 686: }
> 687: .page-search-info {
> 688:     background-color: #f5f8ff;

reminder: we were going to look at CSS variables to better manage colors

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

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