Accessibility of JDK API documentation: headings

[David Holmes]

Hi Jon,

On 6/03/2019 11:04 am, 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.

Is this:

<h2 title="Interface ExecutorService" class="title">Interface 
ExecutorService</h2>

one of the h2's that will now be a h1?

If so, if the page heading is a h1 for a given class or interface, then 
I would have expected the field/method/constructor sections to 
implicitly act like h2 (as they are the structural entities of the 
class/interface), and so within that text h3 would be the logical 
heading to use - ref: JDK-8220248. Using h2 in such contexts just seems 
wrong to me.

>   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>.

?? What happened to h3? And how does this relate back to "the main 
heading is now h1"?

>   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.

Well that makes perfect sense if you are writing a book chapter, or some 
normal multi-part text document. But the API pages are not like that, 
they are more like advanced tables, and the use of any heading tag 
within table cells is highly questionable to begin with. So I'm not 
seeing how these rules really apply to our API docs.

Thanks,
David
-----

> 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
>