Accessibility of JDK API documentation: headings

[David Holmes]

On 11/03/2019 1:42 pm, Jonathan Gibbons wrote:
> 
> 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.

It may be rendered as a list but the whole thing has the look of a 
complex table. Regardless, the "headings" within those entries do not 
relate to any overall heading structure for the entire page.

> 
> 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.

Sorry but I can't see how changing h3 to h2 within a 
field/method/constructor improves anything. Those h3 don't relate to the 
existing h1 except in the loosest possible way. They don't define 
subsections of the original h1 (which is what an h2 would be doing).

You'd be better off replacing them with non-header tags IMHO.

David
-----

> -- Jon
>