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

[Jonathan Gibbons]

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.