Accessibility of JDK API documentation: headings
Sergey.Bylokhov at oracle.com
Wed Mar 6 01:08:51 UTC 2019
Is it possible to catch such issues using doclint?
On 05/03/2019 17:04, Jonathan Gibbons wrote:
> 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
> at <h4>.
> 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
> documentation comments.
> 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
> a comment.
> There are 69 instances of this issue.
> -- Jon
Best regards, Sergey.
More information about the jdk-dev