JEP 225: Javadoc SearchJEP 225: Javadoc SearchOwnerBhavesh PatelTypeFeatureScopeJDKStatusClosed / DeliveredRelease9Componenttools / javadoc(tool)Discussionjavadoc dash dev at openjdk dot java dot netEffortMDurationMReviewed byAlex Buckley, Brian Goetz, Jonathan Gibbons, Kumar SrinivasanEndorsed byBrian GoetzCreated2014/05/29 03:05Updated2017/06/05 19:09Issue8044243Summary
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

InstallingContributingSponsoringDevelopers' GuideVulnerabilitiesJDK GA/EA BuildsMailing listsWiki
                      · IRCBylaws · CensusLegalWorkshopJEP ProcessSource codeMercurialGitHubToolsGitjtreg harnessGroups(overview)AdoptionBuildClient LibrariesCompatibility & Specification ReviewCompilerConformanceCore LibrariesGoverning BoardHotSpotIDE Tooling & SupportInternationalizationJMXMembersNetworkingPortersQualitySecurityServiceabilityVulnerabilityWebProjects(overview,
      archive)AmberBabylonCRaCCaciocavalloClosuresCode ToolsCoinCommon VM InterfaceCompiler GrammarDetroitDevelopers' GuideDevice I/ODukeGalahadGraalIcedTeaJDK 7JDK 8JDK 8 UpdatesJDK 9JDK
      (…,
       21,
       22,
       23)JDK UpdatesJavaDoc.NextJigsawKonaKullaLambdaLanaiLeydenLilliputLocale EnhancementLoomMemory Model UpdateMetropolisMission ControlMulti-Language VMNashornNew I/OOpenJFXPanamaPenrosePort: AArch32Port: AArch64Port: BSDPort: HaikuPort: Mac OS XPort: MIPSPort: MobilePort: PowerPC/AIXPort: RISC-VPort: s390xPortolaSCTPShenandoahSkaraSumatraTiered AttributionTsanType AnnotationsValhallaVeronaVisualVMWakefieldZeroZGC

        © 2024 Oracle Corporation and/or its affiliates
        Terms of Use
        ·
        
            License: GPLv2
        · Privacy
        · Trademarks
