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

Javadoc: links to type parameters actually generate links to classes

    XMLWordPrintable

Details

    • Fix Understood
    • generic
    • generic

    Description

      ADDITIONAL SYSTEM INFORMATION :
      $ /usr/lib/jvm/java-19-openjdk-amd64/bin/javadoc --version
      javadoc 19.0.2

      A DESCRIPTION OF THE PROBLEM :
      Per "Documentation Comment Specification for the Standard Doclet" (see e.g. https://docs.oracle.com/en/java/javase/20/docs/specs/javadoc/doc-comment-spec.html), @link syntax can be used with a "label that points to the documentation for the specified module, package, class, or member name of a referenced class".

      The Javadoc tools doesn't handle mentions of _type parameters_ in @link syntax very well. It doesn't consider them unknown references, and actually generates HTML anchors, but the URL and text of the anchors aren't what the user might expect.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      1. Run the source code below against the {{javadoc}} tool
      2. Observe the generated HTML -- look for where @links are used to link to type parameters of the class and of the method.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The javadoc tool either produces an error about @links to type parameters ("reference not found", similar to "parameter" in the example code), or a proper non-broken link to the specified type parameter is generated. See mentions of "id attribute/anchor" and "target" in JDK-8302449.
      ACTUAL -
      Each @link to a type parameter gets converted into a link to the class DemonstrationOfTypeParameterLinks, as if we had written "{@link DemonstrationOfTypeParameterLinks}"

      ---------- BEGIN SOURCE ----------

      /**
       * <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html">Documentation of
       * javadoc</a> makes it clear that Javadoc tag "link" can only be used to link to:
       * "the documentation for the specified module, package, class, or member name of a referenced class".
       * <p>
       * However, it is also possible to "link" to type parameters: {@link TYPE}.
       * When Javadoc is rendered as HTML the "link" to the type parameter in the
       * previous sentence gets converted into a link to the <em>class</em>.
       *
       * @param <TYPE> The type of element. This is the actual documentation of the
       * type parameter
       */
      public class DemonstrationOfTypeParameterLinks<TYPE> {
      /**
      * <p>
      * {@code @param element} is missing below, so javadoc gives
      * a warning:
      * <pre>
      * .../DemonstrationOfTypeParameterLinks.java:23: warning: no @param for element ...
      * </pre>
      * <p>
      * We aren't allowed to link to the {@code parameter}, javadoc gives
      * an error:
      * <pre>
      * .../DemonstrationOfTypeParameterLinks.java:16: error: reference not found
      * </pre>
      * <p>
      * When "linking" to the type parameter {@link E} of the method or type
      * parameter {@link TYPE} of the class, the rendered HTML instead contains
      * links to the class {@link DemonstrationOfTypeParameterLinks}.
      * <p>
      * It would be preferable, if {@code javadoc} either:
      * <ul>
      * <li>complained about such non-working {@code {@link}} tags</li>
      * <li>or actually allowed linking to type parameters</li>
      * </ul>
      *
      * @param parameter the parameter of this method
      * @param <E> the type of the element
      */
      public <E> void methodName(int parameter, E element) {
      }
      }

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

      FREQUENCY : always


      Attachments

        Issue Links

          Activity

            People

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

              Dates

                Created:
                Updated: