RFR: 8253117: Replace HTML tables in javadoc summaries with CSS grid elements

Hannes Wallnöfer hannesw at openjdk.java.net
Fri Sep 18 15:10:56 UTC 2020


This changes the output of the `html.markup.Table` class to plain `div` elements, using CSS Grid Layout to display them
in a tabular format.

I decided against renaming the Table class and related identifiers even though it does no longer emit an HTML <table>
element. I admit this results in a somewhat odd mismatch in a few places, but on the other hand the generated HTML
still represents tabular data. Also, the changes are much easier to understand and review this way. I'm open to
renaming things if we can find a better terminology.

I simplified the existing code in quite a few places:

 - Removed the setters for table tab ids and the browser tab script. The ids are now derived from the main table id which
   makes them unique even with multiple tables per page (provided the tables have different ids), and the browser script
   will always work for the used ids.
 
 - Removed the complex tab selection scheme based on bitwise operations and replaced it with one CSS class per tab. The
   elements making up a table row will have a CSS class for each tab they belong to. The CSS class names are derived from
   the table id as well.

 - Reduced per usage style classes for summary tables, thereby simplifying the style sheet. Instead of having a CSS class
   for each useage of a table (e.g. `member-summary`, `type-summary` etc) there is only one common CSS class for summary
   tables as well as one specifying the number of columns to use, e.g. `two-column-summary`, `three-column-summary` etc.

The rendering and spacing of the tables should be the same as previously. There are a few exceptions:

 - The style sheet has additional media queries to switch the layout of tables when the width of the browser window
   becomes very narrow. This happens at different thresholds for tables with two, three, or four columns. Note that these
   theresholds are based on heuristics, it is what I have found to work well under most circumstances.

 - The new grid never grow larger than the width available in the browser. When a table cell becomes too narrow to contain
   its content, the cell becomes scrollable. This happens very rarely and is not too disturbing IMO.

 - Spacing of columns is usually a bit different than previously. Grids offers very complex layout options, and the
   setting I came to use partitions space depending on the width of cell contents.

Here are the API docs for java.base rendered with these changes:
http://cr.openjdk.java.net/~hannesw/8253117/api.00/

Here are the API docs with these changes and additionally the patch for JDK-8248566 (mobile browser optimizations)
applied: http://cr.openjdk.java.net/~hannesw/8253117/api.00.mobile/

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

Commit messages:
 - Fix trailing whitespace
 - Clean up comments and styles
 - Restore table spacing
 - Adapt tests to grid summaries
 - Use CSS Grid Layout for javadoc summaries

Changes: https://git.openjdk.java.net/jdk/pull/253/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=253&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8253117
  Stats: 2323 lines in 61 files changed: 257 ins; 653 del; 1413 mod
  Patch: https://git.openjdk.java.net/jdk/pull/253.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/253/head:pull/253

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


More information about the javadoc-dev mailing list