RFR: 8215307: Pages do not have <h1>

[Jonathan Gibbons]

On 1/26/19 2:45 AM, Martin Desruisseaux wrote:
> 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?

Yes and no.  Yes, it has been talked about; no, it has not been discussed
enough for us to pursue it at this point. I have been anticipating that the
next step is to update the javadoc doc comment specification [1] to define
the HTML headings to use in comments. That may be the time to consider
the provision of new tags. But, even if we define javadoc tags that can be
used, we still have to accept HTML headings in the comment, and specify
their effect.

[1] https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html

>
> 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.
It is definitely the case that it will be easier to leverage new 
features in HTML 5
when we drop the need to support both versions. I've not yet played with
<details> and <summary>.  The one thing I will note is that these terms
do not correspond with the way these terms are presented in the generated
documentation. That's not in itself a problem; just a caution to those 
looking
at these tags.

One similar/related change that came to mind while debugging recent changes
is that we use <div> a lot in the output, and that in a number of 
places, we could
reasonably use <section> instead.  I suspect we should start keeping a 
list of
possible enhancements.

-- Jon

>
>      Martin
>
>