JDK-8288900 : Add structural HTML elements for table rows
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 16,17,18,19,20,21
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2022-06-21
  • Updated: 2025-02-18
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdUnresolved
Related Reports
Relates :  
JDK-8253117 - Replace HTML tables in javadoc summaries with CSS grid elements
Description
Since we are using CSS grid layout for tables in javadoc generated pages (JDK-8253117) the structure of table data is no longer reflected in the markup - it's just a linear sequence of `<div>` elements with specific attributes.

It would be nice to have HTML elements that semantically represent table rows again. The most likely way we can implement this is by using the `display: contents` CSS property which allows to apply grid layout to the child nodes of a grid element. This article [https://hidde.blog/more-accessible-markup-with-display-contents/] gives a good overview about the state of `display: contents` and its role for more accessible web pages. 

`display:contents` is now implemented in most browsers we support[1], but we also must make sure our solution renders gracefully on older browsers, which may force us to delay this enhancement for a bit.

[1]: https://caniuse.com/css-display-contents
Comments
Early 2025 update: Subgrid is now labeled "Baseline 2023 - Newly available across major browsers": https://caniuse.com/?search=subgrid Subgrid is definitely the proper way to do go to enable single row elements for grid tables. The feature will also likely be used in JDK-8345555 for implementing a two-column layout for search results. While that enhancement is targeted to 25, I still consider it early to do the same for summary tables in 25, as summary tables are a central part of API docs that will make the whole documentation almost unusable when misaligned, while search is still quite usable with misaligned columns. So I think we can target this issue in the not too distant future post 25. Using Subgrid will also allow us to get rid of hard-coded even/odd table row classes, as striped tables can be more conveniently implemented using `:nth-child(even)` and `:nth-child(odd)` CSS pseudo-classes.
18-02-2025
As of mid 2024, the CSS Subgrid [1] feature is implemented in all relevant desktop and mobile browsers. This is relevant because it is an alternative technology for adding structural elements for table rows, and there are usability concerns related to the `display:contents` feature (buttons are not accessible with `display:contents` applied, which may or may not be a problem in our use case). [1] https://caniuse.com/?search=subgrid Support for CSS Subgrid is very recent in all browsers, so it will some more time until it can be used in JavaDoc.
02-07-2024