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

javadoc can't resolve @link tags (in a case too special to describe in 1 line)

    XMLWordPrintable

Details

    Description



      Name: rmT116609 Date: 10/09/2003


      FULL PRODUCT VERSION :
      Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
      Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

      FULL OS VERSION :
      Microsoft Windows XP [Version 5.1.2600]

      A DESCRIPTION OF THE PROBLEM :
      javadoc can't resolve @link tags referring to Java core platform classes by their short name if the class being documented possesses an anonymous subclass of which an instance is set as a final field in the same class or another documented class. (This is quite an obscure situation, I have to admit, but the test case I have included makes it plain.)

      Note that deleting the "final" keyword or deleting the pair of empty braces ("{ }") after the constructor invocation in the test case removes the problem, showing the relevance of both the "final" modifier and of the anonymous class definition to the problem.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      1. Create a file named "MyClass.java" containing the source code for the test case.
      2. In the same directory, run "javadoc -link <core_api_docs> MyClass.java", where <core_api_docs> stands for the root directory of the JDK API documentation files.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      javadoc should generate the API documentation for the MyClass class without any warning message, and the generated documentation should contain a link to the java.io.File class as a result of the resolution of the {@link File} tag in the source file.
      ACTUAL -
      javadoc produces "reference not found" warning messages and doesn't resolve the {@link File} tag.

      ERROR MESSAGES/STACK TRACES THAT OCCUR :
      javadoc output:

      Loading source file MyClass.java...
      Constructing Javadoc information...
      Standard Doclet version 1.4.2_01
      Generating constant-values.html...
      Building tree for all the packages and classes...
      Building index for all the packages and classes...
      Generating overview-tree.html...
      Generating index-all.html...
      MyClass.java:10: warning - Tag @link: reference not found: File
      Generating deprecated-list.html...
      Building index for all classes...
      Generating allclasses-frame.html...
      Generating allclasses-noframe.html...
      Generating index.html...
      Generating packages.html...
      Generating MyClass.html...
      MyClass.java:10: warning - Tag @link: reference not found: File
      MyClass.java:10: warning - Tag @link: reference not found: File
      Generating package-list...
      Generating help-doc.html...
      Generating stylesheet.css...
      3 warnings

      REPRODUCIBILITY :
      This bug can be reproduced always.

      ---------- BEGIN SOURCE ----------
      import java.io.File;

      public class MyClass
      {
        public static final MyClass INSTANCE = new MyClass() { };

        /**
         * A {@link File} instance.
         */
        public File file = null;
      }
      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      The simplest workaround I have found is to remove the "final" modifier that is causing the problem. If you don't want to remove the "final" modifier, then using fully qualified names in all problematic @link tags will work too.
      (Incident Review ID: 214793)
      ======================================================================

      Attachments

        Activity

          People

            bpatel Bhavesh Patel (Inactive)
            rmandalasunw Ranjith Mandala (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: