<Swing Dev> RFR: 8260314: Replace border="1" on tables with CSS

[Jonathan Gibbons]

On Tue, 26 Jan 2021 18:33:48 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>>> Probably we can import the CSS used by the javadoc itself?
>> 
>> We do. For example, [AWT Modality in JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/java/awt/doc-files/Modality.html) has borders because of `border="1"` attribute. If you remove it or change it to `border="1"` in Developer Tools in browser, the borders around cells disappear.
>> 
>> However, I looked into it further: there are tables in Javadoc comments. One example is [AWTKeyStroke constructor](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/java/awt/AWTKeyStroke.html#%3Cinit%3E()) which uses `class="striped"`. In most cases, classes in java.desktop module use striped tables.
>> 
>> There's also `plain` class. I've found one usage of `class=plain"` in [NumericShaper class](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/java/awt/font/NumericShaper.html). This style has collapsed borders around each cell. It looks similar to what we have now in “plain” HTML documents, yet by default the borders are not collapsed, that is you see borders around each individual cell.
>> 
>> The stylesheet also declares `borderless` class which has no borders.
>> 
>> For the consistent look and feel of documentation, I think `striped` is the most appropriate class. However, I prefer `plain` class for `componentProperties.html` file.
>
> I updated all the tables with `class="striped"`.
> 
> I've also uploaded the files with different styles for visual comparison:
> 
> ### Current: JDK 15
> 
> - [DesktopProperties.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/java/awt/doc-files/DesktopProperties.html)
> - [Modality.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/java/awt/doc-files/Modality.html)
> - [gif_metadata.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/imageio/metadata/doc-files/gif_metadata.html)
> - [tiff_metadata.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/imageio/metadata/doc-files/tiff_metadata.html)
> - [componentProperties.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/plaf/synth/doc-files/componentProperties.html)
> - [synthFileFormat.html](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/plaf/synth/doc-files/synthFileFormat.html)
> 
> ### Manual: as suggested initially
> 
> - [DesktopProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/java/awt/doc-files/DesktopProperties.html)
> - [Modality.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/java/awt/doc-files/Modality.html)
> - [gif_metadata.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/javax/imageio/metadata/doc-files/gif_metadata.html)
> - [tiff_metadata.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/javax/imageio/metadata/doc-files/tiff_metadata.html)
> - [componentProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/javax/swing/plaf/synth/doc-files/componentProperties.html)
> - [synthFileFormat.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v1-manual/api/java.desktop/javax/swing/plaf/synth/doc-files/synthFileFormat.html)
> 
> ### Striped: `class="striped"`
> 
> - [DesktopProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/java/awt/doc-files/DesktopProperties.html)
> - [Modality.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/java/awt/doc-files/Modality.html)
> - [gif_metadata.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/javax/imageio/metadata/doc-files/gif_metadata.html)
> - [tiff_metadata.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/javax/imageio/metadata/doc-files/tiff_metadata.html)
> - [componentProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/javax/swing/plaf/synth/doc-files/componentProperties.html)
> - [synthFileFormat.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v2-striped/api/java.desktop/javax/swing/plaf/synth/doc-files/synthFileFormat.html)
> 
> ### Plain: `class="plain"`
> 
> - [DesktopProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v3-plain/api/java.desktop/java/awt/doc-files/DesktopProperties.html)
> - [Modality.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v3-plain/api/java.desktop/java/awt/doc-files/Modality.html)
> - [componentProperties.html](http://cr.openjdk.java.net/~aivanov/8260314/borders/v3-plain/api/java.desktop/javax/swing/plaf/synth/doc-files/componentProperties.html)

In general, I recommend where possible using the styles provided in the standard stylesheet, for overall visual consistency.

FYI, although it seems like the standard styles work for you in this case, if you should ever need it, javadoc now supports package-specific and module-specific stylesheets. Just put `*.css` files in the `doc-files` subdirectory or a package or module, and javadoc should pick it up and use it.

-------------

PR: https://git.openjdk.java.net/jdk/pull/2210