RFR: 8344301: Refine stylesheet for API docs

Hannes Wallnöfer hannesw at openjdk.org
Tue Feb 18 14:08:41 UTC 2025


This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.

List of changes:

 - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
 - Fix font size and line height inconsistencies in many places.
 - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
 - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
 - Add a subtle gray background to code elements in normal text to set them apart.
 - Highlight headings of member details when they are used as link targets.
 - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
 - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
 - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
 - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
 - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
 - Improve styling of additional HTML doc-files.
 - Remove animations and smooth scrolling in order to improve accessibility.
 - Various cleanup.

There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.

[Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).

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

Commit messages:
 - Update copyright headers
 - 8344301: Refine stylesheet for API docs

Changes: https://git.openjdk.org/jdk/pull/23678/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23678&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8344301
  Stats: 281 lines in 5 files changed: 114 ins; 88 del; 79 mod
  Patch: https://git.openjdk.org/jdk/pull/23678.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23678/head:pull/23678

PR: https://git.openjdk.org/jdk/pull/23678


More information about the javadoc-dev mailing list