Hi Jon,
I looked at the stylesheet can the descriptive comments for each of the
classes be moved closer to the class itself, ie. just before the
definition ?
Kumar
This is an updated review for the changes to improve tables in java.base.
The changes incorporate earlier review feedback, and also address a
problem that was discovered with nested tables.
The summary of the set of changes since the previous round is:
* A new style class is added for borderless tables, to be used in
preference to a table tag with no class.
* The style classes are now named:
borderless
plain
striped
The longer form using a suffix `-table` was considered, but
generally, there should not be so many style classes that such a level
of discrimination is needed. The names `borderless` and `striped` are
most likely to only apply to tables anyway, and `plain` could
reasonably be used for other elements without conflict.
* Comments are added to the stylesheet regarding these new classes, as
a placeholder until a better specification for the styles in these
stylesheets is created.
* Within java.base, all uses of the `altrows` class have been updated
to use `striped`, and tables with no class attribute have been changed
to explicitly use `borderless`.
Webrevs:
langtools (the stylesheet):
http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/
jdk (changes to java.base):
http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/
API showing the combined effect of these cahnges:
http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html
-- Jon
On 05/03/2017 03: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
