A DESCRIPTION OF THE PROBLEM :
With the change for <https://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8219801&gt;, header nesting in generated Javadoc has changed. This is likely well-intended, but makes it impossible to write Javadoc that works both with jdk-13 and previous releases.



REGRESSION : Last worked in version 12.0.1

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
sample file:
---
public class JavaDocHtmlHeaderTest {

  /**
    * One sentence.
    * <p>Another sentence
    * <h3>H3</h3>
    * <p>Yet another sentence.
    */
  public void foo() {
  }
}
---

Then run javadoc, such as with:
---
 /usr/local/jdk-13/bin/javadoc JavaDocHtmlHeaderTest.java
---

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Javadoc generation should pass.
ACTUAL -
Fails with:
---
JavaDocHtmlHeaderTest.java:6: error: unexpected heading used: <H3>, compared to implicit preceding heading: <H3>
    * <h3>H3</h3>
      ^
---


---------- BEGIN SOURCE ----------
public class JavaDocHtmlHeaderTest {

  /**
    * One sentence.
    * <p>Another sentence
    * <h3>H3</h3>
    * <p>Yet another sentence.
    */
  public void foo() {
  }
}
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
I understand that the "fix" is to change the "<h3>" to "<h4>". This fixes the issue for jdk-13, but now jdk-12's javadoc generation will break.

This is a severe issue for projects that wish to support a range of JDK versions, such as Java 8, the latest LTS, and the latest & greatest.

Please consider one of these approaches:

- allow to turn off the change in behavior
- add an option that will instruct javadoc to rewrite the <h*> elements (if it can detect the issue, it can theoretically fix it as well)
- backport the change to earlier JDKs

FREQUENCY : always