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

Add module support for @see, @link and @linkplain javadoc tags.

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 15
    • tools
    • None
    • behavioral
    • low
    • This is a generalization of an existing feature.
    • Other
    • JDK

    Description

      Summary

      Extend @see, {@link} and {@linkplain} javadoc tags to support modules.

      Problem

      The javadoc tags @see, {@link} and {@linkplain} are used to refer to elements in other parts of the API, such as packages, classes and members. The tags need to be updated to also be able to refer to modules, and to elements in other modules.

      Solution

      Update the tags @see, {@link} and {@linkplain} to be able to refer to modules and elements in modules.

      All three of these tags take a reference. The set of acceptable references is extended to include:

      • module-name
      • module-name/package-name
      • module-name/package-name.class-name
      • module-name/package-name.class-name#member

      where member may be the name of a field or the signature of a method (i.e. as currently supported.)

      A module may have the same name as a package, meaning that a reference giving just a qualified name may be ambiguous. In this case, the reference will link to the package. To link to the module a trailing / can be appended to the reference:

      • module-name/

      Specification

      The diff to the Documentation Comment Specification for the Standard Doclet is attatched to this issue and displayed inline below:

      diff -r 4941b730f916 closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
      --- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Tue Jun 02 05:26:00 2020 -0700
      +++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Tue Jun 02 17:34:54 2020 +0200
      @@ -294,7 +294,7 @@
       The standard doclet distinguishes this from other cases by searching for a
       less-than symbol (`<`) as the first character.
      
      -* `@see` _package_`.`_class_`#`_member_ _label_
      +* `@see` _module_`/`_package_`.`_class_`#`_member_ _label_
      
       Adds a link with a visible text label that points to the documentation for the
       specified name that is referenced. The label is optional; if it is omitted,
      @@ -303,12 +303,14 @@
       visible text. Use the label when you want the visible text to be different from
       the auto-generated visible text.
      
      -_package_`.`_class_`#`_member_ is any valid program element name that is
      -referenced, such as a package, class, interface, constructor, method or field
      -name. Parts of the name can be omitted as appropriate. The class represents any
      -top-level or nested class or interface. The member represents any constructor,
      -method, or field (not a nested class or interface). If this name is in the
      -documented classes, then the standard doclet creates a link to it.
      +_module_`/`_package_`.`_class_`#`_member_ is any valid program element name that
      +is referenced, such as a module, package, class, interface, constructor, method
      +or field name. Parts of the name can be omitted as appropriate. The class
      +represents any top-level or nested class or interface. The member represents any
      +constructor, method, or field (not a nested class or interface). If this name is
      +in the documented classes, then the standard doclet creates a link to it. A
      +trailing `/` can be added to a name to refer to a module in the presence of a
      +package or class with the same name.
      
       To create links to external referenced classes, use the `-link` option.
       External referenced classes are classes that are not passed into the `javadoc`
      @@ -584,17 +586,17 @@
      
       #### `{@link}`
      
      -* `{@link` _package_`.`_class_`#`_member_ _label_ `}`
      +* `{@link` _module_`/`_package_`.`_class_`#`_member_ _label_ `}`
      
       Inserts an inline link with a visible text label that points to the documentation
      -for the specified package, class, or member name of a referenced class.
      +for the specified module, package, class, or member name of a referenced class.
       This tag is valid in all documentation comments: overview, module, package,
       class, interface, constructor, method and field, including the text portion of
       any tag, such as the `@return`, `@param` and `@deprecated` tags.
      
       This tag is similar to the [`@see`](#see) tag. Both tags require the same
      -references and accept the same syntax for _package_`.`_class_`#`_member_ and
      -_label_. The main difference is that the `{@link}` tag generates an inline
      +references and accept the same syntax for _module_`/`_package_`.`_class_`#`_member_
      +and _label_. The main difference is that the `{@link}` tag generates an inline
       link rather than placing the link in the "See Also" section.
       The `{@link}` tag begins and ends with braces to separate it from the rest of
       the inline text. If you need to use the right brace (`}`) inside the label,
      @@ -619,7 +621,7 @@
      
       #### `{@linkplain}`
      
      -* `{@linkplain` _package_`.`_class_`#`_member_ _label_ `}`
      +* `{@linkplain` _module_`/`_package_`.`_class_`#`_member_ _label_ `}`
      
       Behaves the same as the `{@link}` tag, except the link label is displayed in
       plain text rather than code font. Useful when the label is plain text.

      Attachments

        Issue Links

          Activity

            People

              hannesw Hannes Wallnoefer
              bpatel Bhavesh Patel (Inactive)
              Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: