JEP 225: Javadoc Search

OwnerBhavesh Patel
Created2014/05/29 03:05
Updated2017/06/05 19:09
TypeFeature
StatusClosed / Delivered
Componenttools / javadoc(tool)
ScopeJDK
Discussionjavadoc dash dev at openjdk dot java dot net
EffortM
DurationM
Priority3
Reviewed byAlex Buckley, Brian Goetz, Jonathan Gibbons, Kumar Srinivasan
Endorsed byBrian Goetz
Release9
Issue8044243

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?

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

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.

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

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: