Accessibility of JDK API documentation: headings

[Jonathan Gibbons]

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