JEP 225: Javadoc Search

OwnerBhavesh Patel
Created2014/05/29 03:05
Updated2016/05/05 07:41
TypeFeature
StatusCompleted
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 generated API documentation that can be used to search for program elements and tagged words and phrases within the documentation. The search box will appear in the header of all pages that are displayed in the main right hand frame.

Goals

The search functionality should be implemented locally, and should 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 source documentation comments. It is also not a goal to change the general three-frame/no-frames layout or their content at this time, although that may be considered in subsequent work.

Motivation

The Javadoc-generated API documentation pages are 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 should 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 will be 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 will be available on the generated API pages, and will provide:

Libraries

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

Testing

Tests will be needed to ensure the following: