RFR: 8215307: Pages do not have <h1>

[Martin Desruisseaux]

Hello Johathan

Le 25/01/2019 à 22:46, Jonathan Gibbons a écrit :

> 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
>
Thanks for the link to relevant W3C pages. I did not noticed that the
final documents differed from the draft in this aspect. Indeed, my
proposal can not apply anymore in the context of latest specification.


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

Understood, thanks for this effort!


> 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>.
>
On the other hand, requiring developers to start heading with <h3> or
<h4> in their comments is error-prone. I guess that the alternative of
defining a new Javadoc tag has already been explored?

Note exactly about <h1> but somewhat related, if we can leverage HTML5
(i.e. HTML4 support is abandoned), what about enclosing each field,
constructor and method definition in a HTML5 <details> and <summary>
elements? With the method signature in <summary> and the comment body in
<details>. This would allow the reader to show only the method details
(s)he wants to see.

    Martin