Accessibility of JDK API documentation: headings

[Lance Andersen]

Hi Jon,

Once we fix (or believe we have), is there a way to validate that we addressed the issue? 

Best
Lance
> On Mar 6, 2019, at 4:06 PM, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> 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
>>> 
>> 
>> 
> 

 <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>