Accessibility of JDK API documentation: headings

[David Holmes]

On 11/03/2019 4:32 pm, David Holmes wrote:
> 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).

Sorry I misread the examples in the bug report - they are not in the 
field/method/constructor entries but the top-level class/interface docs. 
Use of h2 in that context is less problematic. The way we lay things out 
makes it very hard to see where actual "headings are. For example, given:


Module java.base
Package java.util.concurrent.locks
Interface Lock

     All Known Implementing Classes:
         ReentrantLock, ReentrantReadWriteLock.ReadLock, 
ReentrantReadWriteLock.WriteLock

     public interface Lock

where is the h1? I could argue it should be "Interface Lock", with 
"public interface Lock" then arguably a h2, and then the headings in the 
main javadoc would be correctly left as h3.

But if "public interface Lock" is the h1 then the headings would 
correctly be changed to h2.

David
-----

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