Re: RFR: 8223252: Update Javadoc help page with new search features

Jonathan Gibbons Mon, 02 Dec 2019 08:34:04 -0800

Woohoo!  Awesome!

-- Jon

P.S. (Separately) we really should create a library method somewhere tolocalize a list. I have an email thread discussing the issue with L10Nfolk. The use of "," "and" and "or" in the presentation of a list shouldall be localized. If/when we do that, we could update your searchexamples to contain multiple matches.


On 12/2/19 5:54 AM, Hannes Wallnöfer wrote:

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

Re: RFR: 8223252: Update Javadoc help page with new search features

Reply via email to