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

[Jonathan Gibbons]

I like the overall description for the changes. (I've not yet started 
reading the code changes.)

I agree with not changing the name of the Table class. Even before your 
changes, the class had evolved to more than a simple HTML <table>.  It's 
more useful that it represents the abstraction of some tabular data.

-- Jon

On 9/18/20 8:10 AM, Hannes Wallnöfer wrote:
> 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