Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8223552

change in implicit header nesting breaks backwards compatibility

    Details

    • Subcomponent:
    • Introduced In Build:
      b13
    • Introduced In Version:
      13
    • CPU:
      x86_64
    • OS:
      generic

      Description

      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


        Attachments

          Activity

            People

            • Assignee:
              jjg Jonathan Gibbons
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: