Accessibility of JDK API documentation: headings
Jonathan Gibbons
jonathan.gibbons at oracle.com
Wed Mar 6 21:06:43 UTC 2019
Sergey,
> Is it possible to catch such issues using doclint?
In principle, yes; in practice, today: no.
I can and will update doclint to detect these issues, which reduces the
problem to actually running doclint.
Right now, I'm using a custom annotation processor to detect and report
problems. The line-numbers currently point to the declaration to which
the doc comment applies; I hope to increase the resolution to the line
number within the comment, and will include the reports in any bugs that
get filed.
-- Jon
On 03/05/2019 05:08 PM, Sergey Bylokhov wrote:
> Hi, Jonathan.
>
> 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
>>
>
>
More information about the jdk-dev
mailing list