Kumar,
The nature of CSS is such that there is generally no one single definition.
The descriptive comments are just before the shared/common parts of the
definitions.
If I grouped the comment and class definition, someone else would point
out that I could be
sharing common properties.
The better long term solution is a separate document, with examples.
-- Jon
On 05/08/2017 03:12 PM, Kumar Srinivasan wrote:
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:
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
separate rows.
In addition, there is still the default
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.
The ARIA recommendations are to use the summary attribute or
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
