RFR: Update tables in java.base to be HTML5-friendly.
jonathan.gibbons at oracle.com
Wed May 3 22:06:47 UTC 2017
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:
Just puts plain borders around each cell, with no background coloring.
Horizontal borders are not used between cells in the table body;
instead, alternating backgrounds are used to help distinguish the
In addition, there is still the default
These styles are in the langtools webrev, here:
The changes to the doc comments in java.base are in the jdk webrev, here:
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
Doc comments were changed in files in the following packages:
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
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.
More information about the core-libs-dev