JEP 225: Javadoc Search

Summary

Add a search box to API documentation generated by the standard doclet that can be used to search for program elements and tagged words and phrases within the documentation. The search box appears in the header of all pages generated by the standard doclet.

Goals

The search functionality is implemented locally, and does not rely on any server-side computational resources.

Non-Goals

It is not a goal to implement a general search engine to search all of the words in documentation comments. It is also not a goal to change the general three-frame/no-frames layout or their content in this JEP, although that may be considered in subsequent work.

Motivation

The API documentation pages generated by the standard doclet can be hard to navigate if you're not already familiar with their layout.
An external search engine can be used, but that may lead to an out-dated or irrelevant page. The browser's built-in search function can be used, but that is limited to searching within the current page rather than an entire body of documentation.

Description

What can be searched?

• Declared names of modules, packages, types and members are indexed and searchable. Since methods can be overloaded, the simple name of method parameter types are also indexed and can be searched for. The method parameter names are not indexed.

• A search term or a phrase indexed using a new inline tag, @index, are searchable. Other inline tags cannot be nested inside @index. Only the phrase or search term marked with @index, within a declaration's documenttaion comment, can be searched for. For example, the domain-specific term "ulps" is used throughout the java.lang.Math class, but does not appear in any class or method declaration names. In order to help users of the Math API, the API designer could tag various occurrences of "ulps" in class-level or method-level documentation comments. Tagging is achieved using {@index ulps}. "ulps" will be indexed by javadoc.

The format and location of the generated index may change over time and must not be relied upon by other tools.

Preparing to search

By default, running javadoc will generate an index allowing the generated HTML to support a search box. Client-side JavaScript is used to produce search results. The -noindex option to javadoc can be used to disable the indexing and searching capability. As with all other files that may or may not be generated, javadoc does not remove any obsolete files in the output directory. It is the user's responsibility to ensure that the output directory is empty before running javadoc, to ensure there are no obsolete files from prior runs in the output directory.

How to search

A search box is available on the generated API pages, and provides:

• A facility by which search can be invoked based on user inputs. Search input supports camel case search. For example, to search for addFocusListener() method, a user can simply type "addFL" in the search box. Search input does not support regular expressions, although that may be considered in subsequent work.

• Results, including ones that exactly match the entered character(s) followed by ones that contains the entered character(s) anywhere in the string. Multiple results are displayed as a simple scrolling list below the search box. Results are categorized as "Modules", "Packages", "Types", "Members", and "Search Tags" for easier classification and appropriate user selection; and

• Page redirection based on user selection.

Libraries

jQuery UI Autocomplete and JSZip are used as part of the implementation to provide a browser independent auto-complete implementation. This is a client-side feature.

Testing

Tests are provided to ensure the following:

• Accuracy of the search index
• Usage of the new @index tag
• Accuracy of auto-complete selection and redirection
• Validate against malicious injections