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

[Naoto Sato]

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?

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.