javadoc accessibility: headings

[Jonathan Gibbons]

In our ongoing endeavors to improve support in the standard doclet for 
generating accessible 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 will need to be fixed to address the goal 
of being able to generate accessible documentation, and provide to 
accessible JDK documentation.

 1. The standard doclet is inconsistent about its use of headings
 2. The standard doclet provides little-to-no guidance as to the use of
    headings in documentation comments
 3. Many headings in documentation comments do not follow the best
    practices for headings in accessible documents

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.

For more info, see pages like the following:

      * https://www.w3.org/TR/WCAG20-TECHS/G141.html
      * https://www.w3.org/WAI/tutorials/page-structure/headings/

Note: there is no requirement for the standard doclet that all generated 
documentation *must* be accessible; the desired requirement is just that 
it *must be possible* to generate accessible documentation.


  Problems


      1. Inconsistent headings

The standard doclet generates a number of different kinds of pages, such 
as for different kinds of declaration, for indexes, for "use" and "tree" 
pages and so on. Most kinds of pages use <h1> for the main title, but 
overall, most pages do not use <h1> at all, and start at <h2> These are 
all the pages for type declarations (classes, interfaces, enums and 
annotation types.)


      2. Little guidance for use of headings

Perhaps because the pages for type declarations start at <h2>, there is 
an informal guideline to "start at <h3>" but this guideline is overly 
simplistic and often inappropriate. For example, the page for a package 
or module declaration use <h1> for the title, and so any headings in the 
documentation comment should start at <h2>. Even worse, because the 
standard doclet uses headings within the page, any headings in the 
documentation comments for members of a type need to take those 
additional levels of headings into account.


      3. Bad headings in doc comments

Even taking into account the lack of guidance described in the previous 
paragraph, there are some obvious errors in doc comments. These errors 
are reported by accessibility checkers, but the needles get lost in the 
haystack of warnings deriving from the issues arising from the standard 
doclet itself.

Here's one notable error, showing the headings mechanically extracted 
from a current page in the Java SE documentation. Note that the 
top-level H1 is missing (that's a problem in the standard doclet), the 
first H2 and the H3 and H4 that follow are generated by the doclet, but 
there's a spurious H2 that breaks up the sequence of H4 headings for the 
methods under the H3 Method detail heading.

H1: MISSING

  * H2: Class DatatypeFactory
      o H3: Field Summary
      o H3: Constructor Summary
      o H3: Method Summary
      o H3: Methods declared in class java.lang.Object
      o H3: Field Detail
          + H4: DATATYPEFACTORY_PROPERTY
          + H4: DATATYPEFACTORY_IMPLEMENTATION_CLASS
      o H3: Constructor Detail
          + H4: DatatypeFactory
      o H3: Method Detail
          + H4: newDefaultInstance
          + H4: newInstance
          + H4: newInstance
  * H2: Tip for Trouble-shooting
      o H3: MISSING
          + H4: newDuration
          + H4: newDuration
          + H4: newDuration
          + H4: newDuration
          + /etc, more H4 deleted/

There's another example in the current JDK API, where there is no H1 at 
the top of the file (the same as above), but there is an H1 heading 
later on, in the doc comment for a method. That heading is clearly not 
the main heading for the page overall.


    Proposal

  * Introduce a new mode in the doclet such that all headings directly
    generated by the standard doclet follow the best practices for
    hierarchical headings.
  * Update the "Documentation Comment Specification for the Standard
    Doclet" [1] to include guidelines for the use of headings in
    documentation comments in different places, such as top-level
    declarations, member declarations and stand-alone HTML files.
  * Update the headings in the JDK API documentation to follow the
    guidelines for generating hierarchical headings.

Using the new mode to generate hierarchical headings may necessitate 
making changes to documentation comments to achieve the goal. For users 
that do not want to edit their comments and are happy with the current 
behavior, the current behavior will continue to be available until any 
future announcement that it will not be supported. However, the new mode 
will be the default, because even without editing any comments, the 
generated docs will be "less bad" than the current behavior.

  * With the old behavior, all the pages for type declarations have a
    missing <h1>
  * With the new behavior and without editing any comments, the only
    problems in this area will be from those comments that contain
    explicit headings, which overall, are relatively uncommon.


[1] 
https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181214/594fae57/attachment.html>