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
