RFR: 8220497: Improve Javadoc search feature and add test coverage

[Jonathan Gibbons]

Mostly excellent!

Some comments:


    The spec:

The overview  is a bit of a mix of spec and impl details.


      Under Definitions

I was surprised to see the new word "entity" until I realized it needs 
to include both elements and custom searchable items. Maybe that should 
be said somewhere.

"Upper case" and "lower case" are normally written as single words.

Are we allowed non-letter characters in a camel-case search? i.e. should 
the definition of camel-case include the non-alphabetic characters

Should "all-caps" (and "camel-case" include $


      Under Searchable Entities

typo: entitis


      Under Types


Change "consist" to "consists"


      Under each of Packages, Types and Members


The current pattern is "The signature of <plural> consists of the ..."  
It would be more correct to say "The signature of a <single-item> 
consists of ...".


      Under Matching Rules/Left Boundaries:


3rd bullet: why restrict letter following "_" to all-caps, and not after 
"_" in all cases?


      Under Matching Rules/Camel case:


Wouldn't it be better to allow digits and other non-alpha characters, 
treating them as the same as lower-case?


      Under Matching Rules/White space:


It seems a bug that typing excess whitespace should cause the match to 
fail. You should ignore all whitespace everywhere in the search string.


      Under Browser Requirements:


"Requirements" seems like the wrong word. How about "Supported 
Browsers", with a note that it may work on other browsers as well. Also, 
you should support Chrome on All OSs that support Chrome.


    Code

I note the watermark is fixed in English. Is there any easy way to make 
it localizable?

General question, for later: should we publish/use a minified version of 
search.js?

Other functionality questions are implicit in the comments on the spec.

-- Jon

On 03/23/2019 01:01 AM, Hannes Wallnöfer wrote:
> (This was meant to go out yesterday, but the API docs took the whole night to upload, hence the weekend post.)
>
> This is a general overhaul of the javadoc search feature. It consists of a new specification of the search algorithm, new Nashorn based tests and of course the implementation of the new spec itself. The spec can be considered as addendum to JEP 225[1] which introduced the search feature but didn’t go into too much depth about the details of the search algorithm.
>
> [1]: https://openjdk.java.net/jeps/225
>
> Compared to the version I previously posted on this list this new version contains a number of fixes and refinements.
>
> Issue: https://bugs.openjdk.java.net/browse/JDK-8220497
> Spec: http://cr.openjdk.java.net/~hannesw/8220497/spec.00/
> Webrev: http://cr.openjdk.java.net/~hannesw/8220497/webrev.00/
> API docs: http://cr.openjdk.java.net/~hannesw/8220497/api.00/
>
> Thanks,
> Hannes

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190329/03dec82c/attachment-0001.html>