RFR: JDK-8186466: Fix accessibility and other minor issues in java.base

[Naoto Sato]

Thanks for the explanation, Jon. I am fine with the current one.

Naoto

On 8/18/17 5:37 PM, Jonathan Gibbons wrote:
> Hi Naoto,
> 
> Thanks for checking out the changes.
> 
> On 08/18/2017 05:19 PM, Naoto Sato wrote:
>> Hi Jon,
>>
>> Thank you for the cleanup! I looked at j.l.String, 
>> j.t.DateTimeFormatter, and j.u.ResourceBundle and all look good.
>>
>> BTW, I just noticed that in ResourceBundle, line 1330 and so on, there 
>> is a new column "Index" introduced. Is this intentional?
> 
> Yes. It is intentional, although I'm open to better suggestions for the 
> column header, or for other presentations.
> 
> Conceptually, the information is a list of pairs.   The text that 
> precedes the info describes it as
> "the sequence of locale-format combinations to be used to call 
> |control.newBundle|. ".
> HTML can't do a list of pairs as such, and so a table is used. But for 
> accessibility, there must
> be some subset of each row which together uniquely define the row, and 
> so can be used
> as row headers for the data cells in that row.  Typically, the first 
> element is the
> the unique element.  But that is not so in this case ... worse: there is 
> no such column whose
> cells define the row. Both columns contain duplicates.  That means the 
> only combination
> that uniquely defines the row is the entire row, which would mean the 
> table would be
> all header cells and no data cells!
> 
> I went with a solution to add a new column which identifies the position 
> in the sequence.
> If you don't like the extra column, the alternative would be a bulleted 
> or numbered list,
> with the two items of the pair separated by commas or some other 
> punctuation, as in:
> 
>   *       Locale("de", "DE"),     java.class
>   *       Locale("de", "DE") ,    java.properties
>   *       Locale("de"),     java.class
>   *       Locale("de"),     java.properties
>   *       Locale(""),     java.class
>   *       Locale(""),     java.properties
> 
> (In my mail client, that looks like a bulleted list; I don't know how 
> well it will travel
> through the mail system.)
> 
> -- Jon
> 
>>
>> Naoto
>>
>> On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
>>> Please review these fixes for various minor documentation issues in 
>>> the java.base module.
>>> The changes are mostly in java.util and its subpackages, but there is 
>>> some minor cleanup
>>> in previously updated packages as well.
>>>
>>> The primary focus is on addressing accessibility issues. In addition, 
>>> some doc files have
>>> been converted to HTML5. As with all recent fixes like this, there 
>>> should be no change to
>>> the underlying specifications.
>>>
>>> JBS:https://bugs.openjdk.java.net/browse/JDK-8186466
>>> Webrev:http://cr.openjdk.java.net/~jjg/8186466/webrev.00/index.html
>>> API:http://cr.openjdk.java.net/~jjg/8186466/api.00/overview-summary.html
>>>
>>> -- Jon, the Javadoc Janitor
>>>
>>>
>>> Here are more detailed notes on the changes:
>>>
>>> src/java.base/share/classes/java/lang/String.java
>>>      Some greek text that previously used discrete image files for 
>>> the characters
>>>      has been updated to use Unicode characters, specified with HTML 
>>> entities.
>>>      All related image files in the doc-files subdirectory have now 
>>> been removed.
>>>
>>> src/java.base/share/classes/java/lang/doc-files/ValueBased.html
>>>      The file is trivially updated to HTML 5.
>>>
>>> src/java.base/share/classes/java/lang/doc-files/threadPrimitiveDeprecation.html 
>>>
>>>      The file is updated to HTML 5.
>>>
>>> src/java.base/share/classes/java/time/format/DateTimeFormatter.java
>>>      Two missing quote marks are added.
>>>      The quotes are regrettably necessary: some of the examples 
>>> contain spaces,
>>>      and some cells have more than one example,
>>>
>>> src/java.base/share/classes/java/util/Deque.java
>>>      The tables are made accessible.
>>>      Where reasonable, the tables are converted to the de-facto standard
>>>      "striped" style.
>>>
>>> src/java.base/share/classes/java/util/Queue.java
>>>      A table is made accessible, and converted to the de-facto standard
>>>      "striped" style.
>>>
>>> src/java.base/share/classes/java/util/ResourceBundle.java
>>>      A preformatted list is converted to a semantic list.
>>>      The tables are made accessible.
>>>      Where reasonable, the tables are converted to the de-facto standard
>>>      "striped" style.
>>>      Line 3458 and following. Previously, the comment did not display 
>>> correctly
>>>      because javadoc incorrectly treated the dot in this string 
>>> "<code>'.'</code>"
>>>      as the end of the first sentence! The minimal fix would be to 
>>> change that
>>>      string to "{@code .}", but that would be stylistically inconsistent
>>>      with the rest of the comment. There are too many occurrences of
>>>      <code>...</code> in the file as a whole to change them all at 
>>> this time,
>>>      so the compromise is just to replace the occurrences in this 
>>> comment.
>>>      Introducing more cleanup for existing uses of <code>...</code> is a
>>>      topic for another day.
>>>
>>> src/java.base/share/classes/java/util/concurrent/BlockingDeque.java
>>>      The tables are made accessible.
>>>      In the second table, the "Insert"/"Remove"/"Examine" headings
>>>      are moved from embedded rows to a new left-most column
>>>      for consistency with other similar tables.
>>>
>>> src/java.base/share/classes/java/util/concurrent/BlockingQueue.java
>>>      The table is made accessible.
>>>
>>> src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
>>>      The table is made accessible.
>>>
>>> src/java.base/share/classes/java/util/doc-files/coll-designfaq.html
>>>      The file is updated to HTML 5.
>>>      The name attributes, which each duplicated the id attribute on
>>>      the same enclosing <a> element, are removed.
>>>
>>> src/java.base/share/classes/java/util/doc-files/coll-index.html
>>>      The file is trivially updated to HTML 5.
>>>
>>> src/java.base/share/classes/java/util/doc-files/coll-overview.html
>>>      The file is updated to HTML 5.
>>>      A style is added for the table declared in this file.
>>>      An alternative edit, to import and use the main javadoc stylesheet
>>>      was consider, but caused too many other visual issues.
>>>      Eventually, we should change all doc-files/*.html files to use the
>>>      standard stylesheet(s).
>>>
>>> src/java.base/share/classes/java/util/doc-files/coll-reference.html
>>>      The file is updated to HTML 5.
>>>
>>> src/java.base/share/classes/java/util/regex/Pattern.java
>>>      This was the hardest file to update; in particular, the main
>>>      table listing the supported pattern constructs. Several solutions
>>>      were attempted, such as splitting the table up into smaller tables,
>>>      and moving the subheadings to a new column on the left.
>>>      As the saying goes, this solution is the worst, except for all
>>>      the others. It has the singular advantage of preserving the
>>>      existing visual appearance for most users, even if the
>>>      source code is somewhat dominated by the attributes to
>>>      make the table accessible, and to retain the same visual
>>>      presentation.  This table, and some of tables in the Collections
>>>      API, highlight the shortcomings in javadoc's support for
>>>      custom styles when it is really, really needed. In principle, all
>>>      of the style attributes in the main table could be placed
>>>      much more succintly in some local stylesheet.
>>>      The other edits in this file are more obvious and straightforward.
>>>
>>> src/java.base/share/classes/java/util/spi/CalendarNameProvider.java
>>>      The tables are made accessible.
>>>      Again, custom stylesheets would simplify the source code.
>>>
>>> src/java.base/share/classes/java/lang/doc-files/*.gif (deleted)
>>>      See comments above for 
>>> src/java.base/share/classes/java/lang/String.java.
>>>      The files 
>>> src/java.base/share/classes/java/lang/doc-files/javalang.doc.anc*.gif
>>>      appear to be orphaned relics of earlier versions of the API.
>>>      The images exist in releases at least as far back as 1.4, and look
>>>      like they might have been part of some mathematical 
>>> representation of
>>>      a string hash function, although I've not been able to track down
>>>      where the images were used.
>