Hi Jon,
The changes in the java.lang and java.math packages look fine.
Cheers,
-Joe
On 5/3/2017 3:06 PM, Jonathan Gibbons wrote:
This is a review request for two co-dependent fixes.
JDK-8179592: Update tables in java.base to be HTML 5-friendly.
JDK-8179479: Add new styles to enable HTML 5 tables
In doc comments, some of the HTML 4.01 attributes for tables are no
longer available in HTML 5, and CSS should be used instead.
To this end, some updates have been made to the main/default
stylesheet used by javadoc, to define two new CSS classes for tables.
The new classes are:
<table class="plain">
Just puts plain borders around each cell, with no background
coloring.
<table class="altrows">
Horizontal borders are not used between cells in the table body;
instead, alternating backgrounds are used to help distinguish the
separate rows.
In addition, there is still the default
<table>
No borders.
These styles are in the langtools webrev, here:
http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev/
The changes to the doc comments in java.base are in the jdk webrev, here:
http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev/
summary vs. <caption>
The ARIA recommendations are to use the summary attribute or
<caption> tag ... but the summary attribute is no longer allowed in
HTML 5. In general, the text that has been provided for a summary is
not suitable for direct use as a caption. The temporary workaround is
to use a caption that is not displayed. In time, the appropriate API
owners should update the use of these undisplayed table captions, to
modify the text of the caption and make the caption displayed (by
removing style="display:none").
Doc comments were changed in files in the following packages:
java.io
java.lang
java.lang.invoke
java.lang.reflect
java.math
java.net
java.nio.channels
java.nio.charset
java.nio.file
java.nio.file.attribute
java.nio.file.spi
java.security
java.security.cert
java.text
java.time.chrono
java.time.format
java.time.temporal
java.util
java.util.concurrent
java.util.regex
java.util.spi
javax.net.ssl
The intent is that the only changes in this webrev are to the HTML 5
markup. There should be no significant changes to the text in any doc
comment.
The decision to add the styles to the default stylesheet at this late
stage in the release is not taken lightly, and is seen as a temporary
measure. JDK-8177283 is a wishlist enhancement for updates to javadoc
support of stylesheets, which includes the desire to move JDK-specific
styles to a JDK-specific stylesheet.
This review is primarily about continuing the ongoing effort to make
our docs be HTML 5 compliant. I would prefer not to get into extended
discussions about which style class to use for each table, and what
the exact definition of the styleclasses should be at this time. But
appropriate review feedback is obviously welcome.
-- Jon
