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

[Jonathan Gibbons]

On 08/22/2017 01:54 PM, mandy chung wrote:
>
>
> 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.

Specdiff has some amount of trouble, and so I don't entirely understand 
or trust what
it was trying to show me.   The hard part of this is the updates to the 
big table at the
beginning.  To verify that no obvious changes to the spec have 
accidentally been made,
I cut-n-pasted the table contents into a plain-text file, for the 
generated API page,
before and after the changes. When comparing the two text files, the 
only changes
are extra blank lines in the original version, caused by empty table 
rows, which have
been eliminated in the new version by using CSS to provide extra 
whitespace before
the internal headings. Apart from these blank lines, the textual content 
of the tables
is the same, before and after the changes.

>
> 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