JDK-8199895 : javadoc tool generates pages with an invalid heading order
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11
  • Priority: P3
  • Status: Resolved
  • Resolution: Duplicate
  • Submitted: 2018-03-20
  • Updated: 2019-05-21
  • Resolved: 2019-05-21
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 13
13Resolved
Related Reports
Duplicate :  
JDK-8219801 - Pages do not have

Duplicate :  
JDK-8215307 - Pages do not have

Relates :  
JDK-8199176 - Accessibility issues in java.base docs
Description
When the javadoc tool compiles a java doc, it adds a title with a <h1> header tag. If the source starts with a header lower than h2, such as h3 in the following cases, the resulting page will have an invalid heading order.

While we're fixing these particular cases manually, it would be good if the tool could be improved to recognize the issue and fix it during the compilation process.

3. Heading order invalid
docs/api/java.base/java/time/temporal/package-summary.html <h3>Fields and Units</h3>
docs/api/java.base/java/time/chrono/package-summary.html <h3>Example</h3>
docs/api/java.base/java/time/zone/package-summary.html <h3>Package specification</h3>
docs/api/java.base/java/time/package-summary.html <h3>Dates and Times</h3>
docs/api/java.base/java/time/format/package-summary.html <h3>Package specification</h3>
docs/api/java.base/java/lang/package-summary.html <h3>Character Encodings</h3>
docs/api/java.base/java/nio/file/package-summary.html <h3><a id="links">Symbolic Links</a></h3>
Comments
This was fixed in JDK-8219801 and JDK-8215301
21-05-2019
Whether it is <h1> or {@h1} or {@title}, none of them address the underlying problem, that needs to be addressed, which is re-examining the structure of the doclet-generated pages, and from that to the recommendation of what we recommend folk to use. The surface syntax is just syntactic sugar for a bikeshed discussion down the road.
23-03-2018
Another idea may be a javadoc tag {@title ...} or {@subtitle ...}. One could then use @title if they really feel like it, such as in this package-summary, the "Summary of relevant Java Virtual Machine changes" was tagged with <h1>: https://docs.oracle.com/javase/10/docs/api//java/lang/invoke/package-summary.html The benefit will be consistency, that they will be javadoc-generated tags controlled by the stylesheet, together with other elements such as the Interface/Class Summary, and other tags, e.g. @since.
23-03-2018
What I meant was that {@h<number> text} where number is the number of levels down from the lowest level generated by the javadoc tool, which means the javadoc tool converts {@h<number> } to <h(lowest heading level generated by the tool + <number>>. For example, {@h1} is converted to <h2> (h1+1) if the tool adds <h1>, or <h3> if the lowest level it adds is <h2>. It's not ideal since it's unusual. It may also result in a heading being too small if the original doc has many levels. The later is probably unlikely to happen since a javadoc is seldom that big. If different pages provide different levels of "boilerplate" headers, that makes it hard to explain in the documentation/guide too. Some degree of "standardization" on what the doclet generates may be needed.
21-03-2018
Actually, no it doesn't help to add {@h1} etc ... that's just syntactic sugar for what the user could write manually in HTML. The problem is that different pages provide different levels of "boilerplate" headers ... so we have a general dilemma of whether to have "no gaps" in the headers, meaning that otherwise similar user-headers may appear differently on different pages, or have "gaps" in the headers, so that headers which should appear similar do indeed appear similar. At some level, the problem is from the doclet generating different amounts of headers in different pages.
21-03-2018
My first thought was to create a record on the issue. Glad to know it actually helps :-) Would it make sense to create a new javadoc tag? Something like {@h<number> text}? The user content would start with {@h1 text}, and {@h2 ...} and so on if there are more levels. Then, it's up to the javadoc tool to renumber them correctly based on the other parts that it may add.
21-03-2018
I would question whether the right decision is simply to renumber <h3> up to <h2>. That seems like it would cause inconsistencies across different pages.
20-03-2018
There are various parts to the problem here. 1. sometimes folk don't like the styles in the default javadoc stylesheet 2. javadoc doesn't formally define what headers it generates, and in reality, generates different numbers of headers on different pages ... making it hard for authors to know how many generated headers to allow for. 3. sometimes folk want to assume that the doclet will generate some initial headers on the page, and sometimes they don't. It would be simple to say that user content should start with <h1> (and javadoc will renumber appropriately) but you would normally expect <h1> to go at the top of the page, not part way down as in some of the examples. 4. doclint generally encourages leaving <h1> and <h2> for the doclet (which is why you see many pages using <h3> as the first user-header, but as you are noting here, that may mean gaps in the sequence of headers, when javadoc only generates a single header.
20-03-2018
You have triggered some ideas on how we might address this in javadoc :-) But, any fix is going to be disruptive, so we'll have to see what is the best way forward.
20-03-2018
That's nice. This issue is probably all over the place as in the Java SE API doc. The ones listed above certainly are not the only ones. java.xml for example, also suffers the problem.
20-03-2018
This would be an excellent topic for the proposed new/updated Guide to Writing Documentation Comments!
20-03-2018
Serves as a record then. Would it be feasible to document it?
20-03-2018
Right now, javadoc/doclet never modifies the content of comments. While I agree the possibility of generating bad docs is undesirable, there is no good solution in mind at this time.
20-03-2018