Accessibility of JDK API documentation: headings
jonathan.gibbons at oracle.com
Wed Mar 6 01:04:38 UTC 2019
In our ongoing endeavors to improve the accessibility of the Java SE
and JDK API documentation, we need to pay attention to headings.
In this context, "heading" refers to the use of HTML tags <h1> ... <h6>
in the generated documentation.
There are 3 problem areas; all need to be fixed to address the goal
of being able to generate accessible Java SE and JDK API documentation.
1. The standard doclet was inconsistent about its use of headings,
using <h1> for the main heading on some pages, and <h2> for the
main heading on other pages. This has now been fixed, and the
main heading is now <h1> on all pages.
2. The standard doclet provides little-to-no guidance as to the use of
headings in documentation comments. This will be fixed.
To summarize, headings in documentation comments for modules, packages
and types should start at <h2>; headings in documentation comments
for members of a type (field, constructor, method, etc) should start
3. Many headings in documentation comments do not follow the best
practices for headings in accessible documents. For example, many
classes in java.lang.invoke use <h1> repeatedly within the
The best practices are all to facilitate navigating and reading the page
with a screen reader, and can be summarized as follows:
* The main heading for a page should be <h1>
* There should be just one <h1> per page
* Headings should be hierarchical, and without ascending gaps, so <h1>
should be followed by <h2>, <h2> should be followed by <h3> or
another <h2>, etc. It is OK to have "missing" headings when
starting a new higher level section, so that <h4> may be followed by
<h2>, for example; in that case, the <h2> would implicitly end the
preceding section at the <h4> level and the one at the <h3> level.
Now that javadoc has been fixed to generate consistent headings, we need
to address the headings in JDK API comments. The good news is that headings
in comments are relatively rare (about 600 overall) and of those, only about
174 need to be fixed, in 126 files in 49 packages in 12 modules.
Now that we have identified the headings that need to be fixed, I'll be
filing bugs against the various areas. The issues fall into two categories:
* Missing headings: these have generally been caused by changing javadoc
to start headings at <h1> instead of <h2>.
There are 105 instances of this issue.
* Low headings: these are generally because of bad use of headings in
documentation comments, such as the inappropriate use of <h1> or <h2> within
There are 69 instances of this issue.
More information about the jdk-dev