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
