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
