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

Javadoc version 17 issues spurious errors

XMLWordPrintable

      ADDITIONAL SYSTEM INFORMATION :
      Linux (but really system independent)

      A DESCRIPTION OF THE PROBLEM :
      Javadoc for version 17 is much stricter about HTML errors. Mostly this is beneficial but it flags some legitimate constructs as errors. (1) is will not accept legal nested elements such as e<sup>-t<sup>2</sup></sup> which is a perfectly reasonable mathematical expression that HTML accepts/ It will not accept an IFRAME in a javadoc comment although this actually works as expected.

      I have a use-case for using an IFRAME: a factory class with 'set' methods whose first argument is the name of a parameter. The list of parameters can be quite long, so I set up separate HTML pages describing those, and will display that in an IFRAME so that users who want to find specific methods do not have to scroll down past a long list of parameter names to find the method.

      REGRESSION : Last worked in version 11.0.18

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      Create a file named Test.java containing the sample code shown below.
      Then run
         mkdir api
         javadoc -d api Test.java

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The program should run with no errors.
      ACTUAL -
      A warning:
      Test.java:3: warning: nested tag not allowed: <sup>
       * e<sup>-t<sup>2</sup></sup>.

      When an IFRAME (any one) is included in the javadoc commetns, an error results


      ---------- BEGIN SOURCE ----------
      /**
       * An example of a Gaussian distribution, not normalized, is
       * e<sup>-t<sup>2</sup></sup>.
       */
      public class Test {
      }

      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      Use the -Xdoclint option to turn off the checking. Unfortunately this prevents one from catching legitimate errors.

      FREQUENCY : always


        1. Test.java
          0.1 kB
          Anupam Dev
        2. Test-javadoc.png
          37 kB
          Anupam Dev

            Unassigned Unassigned
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: