Accessibility of JDK API documentation: headings
Jonathan Gibbons
jonathan.gibbons at oracle.com
Mon Mar 11 14:41:11 UTC 2019
Hi Lance,
I'm working to update doclint with improve validation of headings. I
hope to post the review for that work today.
-- Jon
On 3/11/19 4:41 AM, Lance Andersen wrote:
> 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 <mailto: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>
>
>
>
More information about the jdk-dev
mailing list