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

[mandy chung]

On 8/18/17 5:03 PM, Jonathan Gibbons wrote:
> Please review these fixes for various minor documentation issues in 
> the java.base module.
I reviewed the following files and the other files are already covered 
by Naoto and Martin.
>
> 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.
>

Change in the above files look okay.
> :
> 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).
>
I agree that it should convert this to use the standard stylesheet 
rather than declaring its own style.  This change is okay for now.
> 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.
>

It is also the hardest to review the diff.   A specdiff would help for 
this specification.  Skimming on the javadoc and seems okay.

The existing source uses a mixture of  {@code...} and <code>...</code>.
> 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.

+1
Mandy