FW: Javadoc violations seen in OpenJDK8

[Pasam Soujanya1]

Follow up mail.

From: Pasam Soujanya1 <psoujany at in.ibm.com>
Date: Thursday, 31 August 2023 at 4:23 PM
To: javadoc-dev at openjdk.org <javadoc-dev at openjdk.org>
Cc: Syed Moinudeen1 <smoinud1 at in.ibm.com>, Shubha S <Shubha.S at ibm.com>, Suman Mitra <summitra at in.ibm.com>
Subject: Javadoc violations seen in OpenJDK8
Hello,

Currently we’re facing 4 violations when generated our API docs using OpenJDK8.

  1.  aria_content_in_landmark
  2.  skip_main_exists
  3.  table_summary_redundant
  4.  text_contrast_sufficient

In OpenJDK11 and OpenJDK17 these issues are not seen.  As per our observation, the Javadoc implementation with respect to below vulnerabilities is different in OpenJDK11/17 compared to OpenJDK8.

Hence, below is our proposed fix.
1. text_contrast_sufficient


Description: When text and its background colors have less than a 4.5 to 1 contrast ratio it can be difficult for people with moderately low vision to read the text without a contrast-enhancing technology. For larger text of 18 point or more, or bold 14 point text, the text and background colors must give at least a 3 to 1 contrast ratio.

Fix for the violation:
Modify stylesheet.css to adjust packagesummary wherever color coding is defined. Below are the changes added to stylesheet which fixed the violation.

File changed: langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/resources/stylesheet.css
Line 383 : Add below lines of code.
.constantsSummary caption a:link, .constantsSummary caption a:visited,
.useSummary caption a:link, .useSummary caption a:visited {
    color:#1f389c;
}
Line 385 : Add .packagesSummary caption a:link,
Line 395 : Add .packagesSummary caption span
Line 407 : Add .packagesSummary caption span.activeTableTab span
Line 429 : Add .packagesSummary caption span.tableTab, .packagesSummary caption span.activeTableTab
Line 438 : Add .packagesSummary .tabEnd
Line 445 : Add .packagesSummary .activeTableTab .tabEnd
Line 453 :  Add .packagesSummary .activeTableTab .tabEnd
Line 463 : Add .packagesSummary td
Line 468 : Add .packagesSummary th
Line 474 : Add .packagesSummary th
Line 488 : Add below lines of code.

.constantsSummary th, .packagesSummary th {

    font-size:13px;

}
Line 490 : Add .packagesSummary td.colFirst, .packagesSummary td.colSecond, .packagesSummary th.colFirst, .packagesSummary th,
Line 497 : Add below lines of code.

.packagesSummary th.colLast, .packagesSummary td.colLast {

    white-space:normal;

}

2. table_summary_redundant

Description: Duplicating a table’s caption and its summary description is repetitive and slows productivity for Assistive Technology users. If used, the summary should provide complementary information not already available in the caption.

Fix for the violation:
Eliminate repetitive caption from adding it to HtmlTree.

File changed : langtools/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlTree.java
Line 652 : Comment out the repetitive content from adding to HtmlTree
//htmltree.addAttr(HtmlAttr.SUMMARY, nullCheck(summary));

The other 2 violations we’re still working on the fix. Please evaluate and suggest if we can merge these fixes to OpenJDK8.

Thanks,
---------------------
Pasam Soujanya
SVT/JCK Test Engineer
IBM Runtime Technologies
Mobile: +91-6301274414








-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20230926/b988d57a/attachment-0001.htm>