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