Please review a new feature to trigger a javadoc search on any javadoc page
through a specially encoded URI fragment.
This allows the search feature to be triggered "locally" in the currently
viewed page by clicking on a link to the search fragment, or "remotely" by
linking to a page whose URI includes a search fragment. The search fragment
uses the following syntax to make it differ from normal page anchors:
#!search=search_term
Although fragments are most commonly used to target elements by their `id`
attribute in HTML documents they are by no means limited to this. The [URI
specification] defines the fragment in very generic terms as additional
information identifying some secondary resource within the primary resource
identified by the URI. There are also many examples of [proposed and existing
uses] of fragment identifiers for similar tasks.
[URI specification]: https://datatracker.ietf.org/doc/html/rfc3986#section-3.5
[proposed and existing uses]:
https://en.wikipedia.org/wiki/URI_fragment#Proposals
I considered other mechanisms such as query strings or javascript links, but
they all have significant drawbacks compared to URI fragments. Query strings
are usually associated with server side processing and cannot be opened without
reloading the page. Javascript links on the other hand cannot be triggered
remotely as part of the primary URI, and there are security issues associated
with them. I think URI fragments are the right tool for the task.
The new feature is deployed in the [Help page] with the search examples, which
should help to popularize the feature. Additionally it should be documented in
the javadoc search spec, for which I'll file a separate JBS issue.
[Help page]: http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html
Below are the URIs for the search examples in the Help page as well as a few
other examples:
http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=j.l.obj
http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=InpStr
http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=HM.cK
http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=stringbuilder.append
http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=java%20collection%20framework
-------------
Commit messages:
- JDK-8248863: Add feature to trigger search via URI fragment
Changes: https://git.openjdk.java.net/jdk/pull/6524/files
Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=6524&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-8248863
Stats: 20 lines in 4 files changed: 16 ins; 0 del; 4 mod
Patch: https://git.openjdk.java.net/jdk/pull/6524.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/6524/head:pull/6524
PR: https://git.openjdk.java.net/jdk/pull/6524
