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

Javadoc tool generates an error instead of a warning for missing references

    Details

    • Type: Bug
    • Status: Open
    • Priority: P3
    • Resolution: Unresolved
    • Affects Version/s: 8, 11, 12, 13
    • Fix Version/s: 14
    • Component/s: tools
    • Subcomponent:
    • Introduced In Build:
      b75
    • Introduced In Version:
      8

      Description

      (Discussed on javadoc-dev mailing list https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-May/001068.html )

      Consider this trivial Java code:

      public class JavadocTest {

          /**
           * Intentionally uses a throws clause referencing an external
           * library which isn't in the classpath
           * @throws ExternalLibraryException some exception
           */
          public void doSomething() throws ExternalLibraryException {

          }
      }

      Using javadoc version, that's shipped in Java:

      java version "1.8.0_172"
      Java(TM) SE Runtime Environment (build 1.8.0_172-b11)
      Java HotSpot(TM) 64-Bit Server VM (build 25.172-b11, mixed mode)


      when I run the javadoc command:

      javadoc JavadocTest.java

      the command ends up with an error (and exits with a non-zero exit code):

      Constructing Javadoc information...
      JavadocTest.java:8: error: cannot find symbol
          public void doSomething() throws ExternalLibraryException {
                                           ^
        symbol: class ExternalLibraryException
        location: class JavadocTest
      Standard Doclet version 1.8.0_172
      Building tree for all the packages and classes...
      Generating ./JavadocTest.html...
      JavadocTest.java:6: error: reference not found
           * @throws ExternalLibraryException some exception
             ^
      Generating ./package-frame.html...
      Generating ./package-summary.html...
      Generating ./package-tree.html...
      Generating ./constant-values.html...
      Building index for all the packages and classes...
      Generating ./overview-tree.html...
      Generating ./index-all.html...
      Generating ./deprecated-list.html...
      Building index for all classes...
      Generating ./allclasses-frame.html...
      Generating ./allclasses-noframe.html...
      Generating ./index.html...
      Generating ./help-doc.html...
      1 error
      1 warning

      It complains of the missing reference to the "ExternalLibraryException"
      which is used in the @throws clause and marks it as an error.

      However, reading the documentation of this tool at [1], the text under
      the "Javadoc options" states:

      "Reports warnings for bad references...

      ...

      Messages may be either warnings or errors, depending on their severity
      and the likelihood to cause an error if the generated documentation were
      run through a validator. For example, bad references or missing Javadoc
      comments do not cause the javadoc command to generate invalid HTML, so
      these issues are reported as warnings."

      This is in contrast to what I'm seeing in the output of the above
      javadoc execution.

      A subsequent command to check the exit code of the javadoc process does indeed confirm that it exited with a non-zero exit code:

      > echo $?
      1

      [1] https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC


        Attachments

          Activity

            People

            • Assignee:
              jjg Jonathan Gibbons
              Reporter:
              jpai Jaikiran Pai
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated: