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

javadoc generates wrong URL fragments for methods in external older javadoc

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 11
    • Fix Version/s: None
    • Component/s: tools

      Description

      A DESCRIPTION OF THE PROBLEM :
      It appears for JDK 10 the URL fragment format for method links changed, not replacing brackets with `-` anymore:
      - JDK < 10: https://docs.oracle.com/javase/9/docs/api/java/lang/Object.html#clone--
      - JDK >= 10: https://docs.oracle.com/javase/10/docs/api/java/lang/Object.html#clone()

      The problem is that if you use the javadoc tool and specify an external `-link`, javadoc appears to always use the method URL fragment format of its version, which is possibly incorrect.

      The most robust way to solve this would be to have `javadoc` generate a machine-readable file (similar to `package-list`) which specifies the javadoc / Standard Doclet version used (unless this represents sensitive information?), so another library generating javadoc against that external documentation can generate the correct links.
      Relying on `--release` or `-source` passed to `javadoc` does not work because external libraries might have used an older version of `javadoc` to create their documentation.

      Note that `-linkoffline` would have to support that in some (backward compatible) way as well.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      1. Create a file called `Javadoc.java` containing the source code provided below
      2. Use JDK 11 (or newer) javadoc: `javadoc -d javadoc -link https://docs.oracle.com/javase/8/docs/api ./Javadoc.java`
      3. Open the generated `javadoc/index.html` in your browser
      4. Click on the external "Object.clone()" link
      -> Notice that it does not scroll to the "clone" method


      ---------- BEGIN SOURCE ----------
      /**
       * @see java.lang.Object#clone()
       */
      public class Javadoc {
      }
      ---------- END SOURCE ----------

        Attachments

          Activity

            People

            • Assignee:
              hannesw Hannes Wallnoefer
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated: