Accessibility of JDK API documentation: headings
jonathan.gibbons at oracle.com
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.
More information about the jdk-dev