Accessibility of JDK API documentation: headings

[Jonathan Gibbons]

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