Accessibility of JDK API documentation: headings

Jonathan Gibbons jonathan.gibbons at
Mon Mar 11 03:42:02 UTC 2019

On 3/10/19 7:32 PM, David Holmes wrote:
> But the API pages are not like that, they are more like advanced 
> tables, and the use of any heading tag within table cells is highly 
> questionable to begin with. So I'm not seeing how these rules really 
> apply to our API docs. 

The "summary" section of the page for a type declaration (class, 
interface, enum etc) is indeed rendered as a table, and only the first 
sentence of each doc comment for a member appears in the table.

The "details" section of the page for a type declaration is rendered as 
a list, not a table, although we have identified some bugs in the 
presentation of that list that we are working to address.

You might still reasonably say that  heading tags are inadvisable within 
the doc comment for a member, and I wouldn't entirely disagree, but the 
fact remains that there are headings in doc comments, and this work is 
about doing the best we can to rationalize the structure of those 
headings, into the structure of the page generated by javadoc.

-- Jon

More information about the jdk-dev mailing list