Thanks Jon, I’ve used your suggestion with minor changes listed below. New webrev: http://cr.openjdk.java.net/~hannesw/8223252/webrev.02/jdk.patch Help doc: http://cr.openjdk.java.net/~hannesw/8223252/api.02/help-doc.html
- Instead of "InputStream" and „InputStreamReader“ it just lists „InputStream“; the „and“ would be subject to localization, and there are several other matches we don’t mention as well. - I used „HM.cK“ and matching „java.util.HashMap.containsKey(Object)“ as third item since I wanted to add an example of „minimal“ camel-case search and one that also covers a member name. Hannes > Am 27.11.2019 um 23:46 schrieb Jonathan Gibbons <[email protected]>: > > Modified suggestion inline: > > > On 11/27/2019 01:40 PM, Jonathan Gibbons wrote: >> Hannes, >> >> It is obviously difficult to abbreviate the full search specification into a >> couple of sentences ;-) >> >> I have a couple of suggestions. >> >> 1. Restructure the text to give all the rules before any of the examples. >> This will make it easier to group and/or add examples. For example: >> >> 219 doclet.help.search.body=You can search for definitions of modules, >> packages, types, fields, methods, \ >> 220 system properties and other terms defined in the API, using some or >> all of the name, optionally using "camel-case". >> For example, >> "j.l.obj" will match "java.lang.Object", "InpStr" will match >> "InputStream" and "InputStreamReader", >> "j.u.HaMa" will match "java.util.HashMap". >> Refer to {0} for a full description of search >> features. >> >> 2. (Restructure it even more to separate the examples into individual >> resources) >> >> >> 219 doclet.help.search.intro=You can search for definitions of modules, >> packages, types, fields, methods, \ >> 220 system properties and other terms defined in the API, using some or >> all of the name, optionally using "camel-case". >> For example: >> doclet.help.search.example.1= >> "j.l.obj" will match "java.lang.Object", >> doclet.help.search.example.2="InpStr" >> will match >> "InputStream" and "InputStreamReader", >> doclet.help.search.example.3="j.u.HaMa" will match "java.util.HashMap". >> doclet.help.search.refer=Refer to {0} for a full description of search >> features. > > Update, we would not expect localizers to localize the examples, so this > could be simplified to > > 219 doclet.help.search.intro=You can search for definitions of modules, > packages, types, fields, methods, \ > 220 system properties and other terms defined in the API, using some or > all of the name, optionally using "camel-case". > For example: > doclet.help.search.example={0} > will match {1} > > doclet.help.search.refer=Refer to {0} for a full description of search > features. > > ... and the list of examples could be hardwired in the code. That also makes > it easier to inject the <code>...</code> > around the content of the examples. > >> >> >> The suggestion is then that the examples are put into a <ul> list. You could >> go for a table but that is generally more work. >> You could do the examples within a loop until you get some sort of "resource >> not found" result. >> For bonus points, use a regex to replace instances of "([^"]+)" with >> "<code>$1</code>" ... i.e. inject <code>...</code> around the contents of >> the quoted string. >> >> >> -- Jon >> >> >> On 11/19/2019 03:43 AM, Hannes Wallnöfer wrote: >>> Jon, >>> >>> I’ve updated the webrev with the comments as suggested. I also update the >>> text to hopefully be a bit clearer. It’s also closer to the previous text, >>> and just adds the following: >>> >>> - mention system properties as searchable items >>> - add example of „j.l.obj“ matching „java.lang.Object“ >>> - Add sentence with reference to search spec >>> >>> New webrev: >>> http://cr.openjdk.java.net/~hannesw/8223252/webrev.01/ >>> >>> New help page: >>> http://cr.openjdk.java.net/~hannesw/8223252/api.01/help-doc.html >>> >>> >>> Hannes >>> >>> >>>> Am 13.11.2019 um 03:00 schrieb Jonathan Gibbons >>>> <[email protected]> >>>> : >>>> >>>> Hannes, >>>> >>>> It is somewhat weird/non-standard to use resources in this way to create >>>> links, and the decision to put the word "the" outside the link, away from >>>> the content of the link "Javadoc Search Specification" is a bit idiomatic. >>>> >>>> I'd suggest prefixing the resources with comments describing the values >>>> that will be substituted. >>>> >>>> # {0} will be replaced by a link derived from the url and title for >>>> the Javadoc Search Specification >>>> 222 doclet.help.search.spec.body=Refer to the {0} for a full description >>>> of search features. >>>> # The URL for the Javadoc Search Specification. {0} will be replaced >>>> by the JDK version number >>>> >>>> 223 doclet.help.search.spec.url= >>>> https://docs.oracle.com/en/java/javase/ >>>> >>>> {0}/docs/specs/javadoc/javadoc-search-spec.html >>>> # The title for the Javadoc Search Specification >>>> >>>> 224 doclet.help.search.spec.title=Javadoc Search Specification >>>> -- Jon >>>> >>>> On 11/12/19 2:30 AM, Hannes Wallnöfer wrote: >>>> >>>>> Please review: >>>>> >>>>> Bug: >>>>> >>>>> https://bugs.openjdk.java.net/browse/JDK-8223252 >>>>> >>>>> >>>>> Webrev: >>>>> >>>>> http://cr.openjdk.java.net/~hannesw/8223252/webrev.00/ >>>>> >>>>> >>>>> >>>>> >>>>> New help page: >>>>> >>>>> http://cr.openjdk.java.net/~hannesw/8223252/api.00/help-doc.html >>>>> >>>>> >>>>> >>>>> Changes in the „search“ section of the help page: >>>>> >>>>> - mention of searchable system properties >>>>> - mention and example of partial matches (in addition to camel-case) >>>>> - new paragraph with link to search spec on docs.oracle.com >>>>> >>>>> Thanks, >>>>> Hannes >>>>> >>>>> >> >
