Martin,
Thank you for your interest in this area; sometimes it's good to know
that other folk care about this sort of stuff as well ;-)
There are a number of different aspects to consider here.
1. Your suggestion presupposes HTML 5. As of right now, javadoc (or more
accurately, the standard doclet) still supports HTML 4 ... but that
being said, work is underway to remove support for HTML 4. javadoc has
given warnings for a while, and it's finally time to remove it.
Suggestions like yours are another reason why it is time to remove
support for HTML 4. [Aside: I note the CSR to remove HTML 4,
JDK-8215578, has just now been approved, so we will soon be proceeding
with the actual removal.]
2. This issue (pages do not have <h1>) is part of the overall ongoing
campaign to fix accessibility issues in generated javadoc, both in
general and in the JDK API in particular. It's the latest in a series of
updates over the past few years, including improved tables, improved use
of regions, and so on. This means that we want to abide by WCAG
standards as well as HTML 5 standards.
3. Your links are for a Working Draft. This seems to be an equivalent
page in the latest version:
https://www.w3.org/TR/html5/sections.html#headings-and-sections
That page does not have the "every <section> has an <h1>" example. It
does have the following text, which ties the heading rank to the nesting
level: /Sections may contain headings of a //rank
<https://www.w3.org/TR/html5/sections.html#rank>//equal to their section
nesting level. Authors should use headings of the appropriate //rank
<https://www.w3.org/TR/html5/sections.html#rank>//for the section’s
nesting level./
Here's a relevant page from WCAG:
https://www.w3.org/TR/WCAG20-TECHS/G141.html
It says: /To facilitate navigation and understanding of overall document
structure, authors should use headings that are properly nested (e.g.,
h1 followed by h2, h2 followed by h2 or h3, h3 followed by h3 or h4, etc.)./
4. This particular bug is (just) about changing the javadoc-generated
headings. It doesn't enforce particular headings within comments,
although it does encourage particular heading levels if doclint is
enabled. You might reasonably surmise that as the overall work moves
forward, we will need to fix up doclint, and the headings in JDK API doc
comments, to achieve our goals in this area. That is "coming soon"; this
review is just the first step, for the javadoc/doclet part of the work.
5. It has been suggested that javadoc should allow headings to start at
h1 in each comment, and that javadoc should adjust them as necessary.
For my part, I think that would be a bad idea, because it could lead to
unexpected differences between the headings in the comments and entries
in the style sheet. It's not good if the user wrote <h1> or <h2> in
their comment, and javadoc rewrites it to <h3> or <h4>.
---
Finally, I welcome any additional input or interpretation of the
prevailing existing standards in this area!
-- Jon
On 01/25/2019 01:41 AM, Martin Desruisseaux wrote:
Hello Jonathan. Thanks for all this work. I was wondering if the use
of <h1>, <h2>, etc. nested inside <section> has been considered for
simplifying the heading ranks? If I understood [1] and [2] correctly,
the following are semantically identical in HTML5:
<h1>XXX</h1>
<section>
<h2>YYY</h2>
<section>
<h3>ZZZ</h3>
and
<h1>XXX</h1>
<section>
<h1>YYY</h1>
<section>
<h1>ZZZ</h1>
Wouldn't the use of <section> allows to reset the <h#> counting to 1
for that section, which would free the developer to care about what
was the rank of last <h#> element? If each field and method is in its
own <section>, wouldn't it allow developers to use <h1>, <h2>, etc. in
their javadoc for each field/method?
Martin
[1]https://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html#headings-and-sections
[2]https://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html#rank
