JDK-8199192 : Some pages generated by javadoc contain accessibility issues
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-03-06
  • Updated: 2018-11-29
  • Resolved: 2018-11-29
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 12
12Fixed
Related Reports
Relates :  
JDK-8214467 - Maintain heading order in javadoc pages
Sub Tasks
JDK-8209052 :  
Low contrast in docs/api/constant-values.html - Resolved
JDK-8210047 :  
some pages contain content outside of landmark region - Resolved
Description
1. Following pages contain content outside of a landmark region. 

api/overview-summary.html
api/*/module-frame.html
api/module-overview-frame.html
api/overview-frame.html
api/allclasses-noframe.html

2. Low contrast. See attached screenshots
docs/api/constant-values.html

3. Heading order invalid
docs/api/*/module-summary.html
<h3>Packages</h3>
<h3>Services</h3>

api/java.base/java/lang/invoke/VarHandle.html
javadoc renders <h2> header <h2 title="Class VarHandle" class="title">Class VarHandle</h2>
there is no <h1> header.
api/java.base/java/lang/invoke/package-summary.html is rendered correctly <h1 title="Package" class="title">Package&nbsp;java.lang.invoke</h1>

Once <h2> is fixed there are will be another issues for "Method Summary", "Field Summary", "Nested Class Summary", etc which are rendered as <h3>.
Comments
Created a seperate bug for Heading order : https://bugs.openjdk.java.net/browse/JDK-8214467. Maintain the heading order is not suggested as a mandatory requirement. The problem mainly occurs with user documentation comments from various classes with different heading levels. All the other accessibility issues reported in this bug as fixed in corresponding sub tasks
29-11-2018
Without frames, only overview-summary.html contains content outside of the landmark region. created sub-task for that
29-08-2018
According to w3c docs, every section can have own order. Like <section A> <h1>Header 1</h1> <section B> <h1> Header 1.2 </h1> </section B> </section A>
13-03-2018
Noted. If nothing else, we should probably try and avoid skipping heading ranks within the same section. In docent/Checker terms, that would suggest maintaining stack of "current header level" and pushing/popping the current value when entering/exiting <section>s. That being said, this specific bug is more about the code generated by the standard doclet itself, which could do a better job to "do the right thing".
12-03-2018
Initially error came from Axe tool https://dequeuniversity.com/rules/axe/3.0/heading-order?application=webdriverjs There are some recommendation: Avoid skipping heading levels: always start from <h1>, next use <h2> and so on. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements Skipping heading ranks can be confusing and should be avoided where possible: Skipping heading ranks can be confusing and should be avoided where possible: Make sure that a <h2> is not followed directly by an <h4>, for example. https://www.w3.org/WAI/tutorials/page-structure/headings/ Sections may contain headings of any rank, but authors are strongly encouraged to either use only h1 elements, or to use elements of the appropriate rank for the section's nesting level. https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html
07-03-2018
My sense was that heading order is no longer so important. Do you have a reference that says it is still important?
07-03-2018
Ok. Will create another bug
07-03-2018
The second screenshot (red text) is not a javadoc problem ... it comes from user content. It's still a valid problem that needs to be addressed; but we'll have to create a separate bug for that and assign it to the component team. It's possible (need to investigate) that the red text comes from our stylesheet, in which case, maybe we could darken the red on behalf of the user content.
07-03-2018
Should definitely fix when in HTML5 mode.
07-03-2018