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

{@value} should be permitted in module documentation

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 12
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source, behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      The tag is permitted in additional places.
    • Interface Kind:
      File or wire format
    • Scope:
      JDK

      Description

      Summary

      Permit {@value} in the documentation comment for a module.

      Problem

      The {@value} inline tag cannot currently be used in the documentation comment for a module, although it is allowed in all other positions for documentation comments.

      The specification is inconsistent. The narrative text says that it may be used in any documentation comment,

      When used with the argument package.class#field in any documentation comment, the {@value} tag displays the value of the specified constant.

      But, the summary at the end of the specification does not list a module declaration among the sites where the tag may be used. This is the extract of the JDK 11 version of the specification:

      Module Declaration
      {@author}, {@deprecated}, {@provides}, {@see}, {@since}, {@serialField}, {@uses}, {@version}
      {@code}, {@docRoot}, {@index}, {@link}, {@linkplain}, {@literal}, {@summary}

      Solution

      Update the implementation to permit the {@value} tag to be used in the documentation comments for modules, and amend the specification appropriately.

      (Note that the overall format of the summary at the end of the specification has already been changed for JDK 12.)

      Specification

      The diff for the change to the Documentation Comment Specification for the Standard Doclet is attached.

      Here is the change inline:

      diff -r 9985a046f1b5 closed/src/jdk.javadoc/share/specs/doc-comment-spec.md
      --- a/closed/src/jdk.javadoc/share/specs/doc-comment-spec.md    Sat Oct 13 13:44:51 2018 -0700
      +++ b/closed/src/jdk.javadoc/share/specs/doc-comment-spec.md    Thu Oct 25 15:02:31 2018 +0530
      @@ -679,7 +679,7 @@
       | [`
      {@summary}
      `](#summary)              | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
       | [`@throws`](#throws)                  |          |         |         |         | ✓     | ✓ |         |
       | [`@uses`](#uses)                      |          | ✓ |         |         |             |         |         |
      -| [`
      {@value}
      `](#value)                  | ✓  |         | ✓ | ✓ | ✓     | ✓ | ✓ |
      +| [`
      {@value}
      `](#value)                  | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
       | [`@version`](#version)                | ✓  | ✓ | ✓ | ✓ |             |         |         |
      
       Notes:

        Attachments

          Activity

            People

            Assignee:
            pmuthuswamy Priya Lakshmi Muthuswamy (Inactive)
            Reporter:
            jjg Jonathan Gibbons
            Reviewed By:
            Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: