Bug ID: JDK-6702376 Javadoc HTML accessibility issues in generated HTML by standard doclet (including WCAG 2.0 issues)

Type: Bug
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 6

Priority: P3
Status: Closed
Resolution: Duplicate
OS: generic
CPU: generic

Submitted: 2008-05-14
Updated: 2011-03-11
Resolved: 2011-03-11

JDK 7
7Resolved

Licensee observes the HTML generated by the Javadoc tool does not meet the
requirements of the Web Content Accessibility Guidelines 2.0 standard:

   http://www.w3.org/TR/WCAG20/

Here are some accessibility problems believed to be found so far.  Note that
this is not an exhaustive list - there are likely to be more problems.

1. The value of the LANG attribute must be set to one of the ISO 639
   language codes.
2. DL tag does not have DT and DD tags nested.
3. Tables should have captions, summary information
4. Table columns should be labeled.
5. Bold characters should be <strong>
6. <p> seems to be used inconsistently

Known failing WCAG 2.0 checkpoints:

1. Using the summary attribute of the table element to give an overview
   of data tables
2. Using semantic elements to mark up structure
3. Using ol, ul and dl for lists
4. Using the lang attribute to identify the language of the page
5. <code> and <pre> are not semantic tags

There are other, more general issues too. For example, the generated HTML contains tags that are opened and not closed, incorrect usage of <dl> tags, and other issues. For example:

   <DL>
   <DT><PRE>public interface <B>JavaReference</B></DL>
   </PRE>

Note how the <PRE> tag starts inside the <dl> and ends outside it.

EVALUATION The javadoc tool has been modified to generate OGHAG compliant HTML. The CR 6851834 that has been implemented contains this fix.
11-03-2011
SUGGESTED FIX The suggested fix for the LANG tag is to introduce a new command-line option to the standard doclet wherein the user would specify the LANG attribute to use. If no such option is supplied on the command line, the standard doclet would assume and use English for this attribute.
24-09-2008
SUGGESTED FIX Most of the suggested fixes should be clear from the second description. The suggested fix for generated tables is from Brian Cragun/Cathy Laws at IBM: Any table that has data content (i.e. is used for more than simple layout), should have 1) Properly tagged headers 2) A summary tag 3) A caption tag This is outlined, at Web Checkpoint 1.3e. Required development techniques Now, applying this to a specific example of representative Javadoc: http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html# The Field Summary and Method Summary tables have content. These tables should declare column headers (and row headers, where applicable). The caption and summary attributes should be used. This is how you might code it up: <table border="1" summary="Field summary table, listing fields, their values and an explanation."> <caption>Field Summary</caption> <tr> <th scope="col">Field</th> <th scope="col">Value and Description</th> </tr> <tr> <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> <CODE>static <A HREF="../../java/util/Comparator.html" title="interface in java.util">Comparator</A><<A HREF="../../java/lang/String.html" title="class in java.lang">String</A>></CODE></FONT></TD> <TD><CODE><B><A HREF="../../java/lang/String.html#CASE_INSENSITIVE_ORDER">CASE_INSENSITIVE_ORDER</A></B></CODE> <BR> A Comparator that orders <code>String</code> objects as by <code>compareToIgnoreCase</code>.</TD> </tr> ... </table> The last column of these tables contains both syntax and a description. I recommend that the description be put in it's own column. This would make the purpose of the text clearer. The Constructor Summary table appears to be a table in a formatting role. However, it really should be a data table with two columns (method, description). This would be consistent with the other tables and easier for users of screen readers.
24-09-2008
EVALUATION After an exchange with IBM, we have distilled down the description into 3 actionable items for this bug: 1. Generated HTML pages coming from the standard doclet should include the LANG attribute in the initial <HTML> tag. 2. Those tables generated by the standard doclet should have captions, labeled column headers, and summary information (see "Suggested fix" for a specific suggestion) [note: this includes both those generated tables already in multi-column format, and those generated tables that would have to be updated to be in multi-column format in order to have clearly labeled individual column headers to aid in comprehensibility for screen reader users] 3. The standard doclet should never generate the <b> tag; use <strong> instead [Note: the originally reported issue "DL tag does not have DT and DD tags nested" is a duplicate of the existing bug #6206490 - see http://bugs.sun.com/view_bug.do?bug_id=6206490 for details]
24-09-2008

Duplicate :	JDK-6851834 - Javadoc doclet needs a structured approach to generate the output HTML.
Relates :	JDK-6786028 - Javadoc HTML WCAG 2.0 accessibility issues in standard doclet - Bold tags should be strong.
Relates :	JDK-6786690 - Javadoc HTML WCAG 2.0 accessibility issues in standard doclet - DL tag and nesting issue.
Relates :	JDK-6786688 - Javadoc HTML WCAG 2.0 accessibility issues in standard doclet - Table must have captions and headers
Relates :	JDK-6786682 - Javadoc HTML WCAG 2.0 accessibility issues in standard doclet - HTML tag should have lang attribute.