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

Support formatting in @value tag

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 20
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Adding an optional new value into the tag, and a default method into the API.
    • Interface Kind:
      Java API, File or wire format
    • Scope:
      JDK

      Description

      Summary

      Update the {@value reference} tag to provide a format string to be given to format the value in documentation.

      Problem

      It is sometimes convenient to be able to override the default presentation of the value referenced in an {@value} tag. This is most obvious for integer values, for which it may be desirable to show the values in octal or hexadecimal format.

      Solution

      Extend the definition of the {@value} tag to allow an optional format string, as defined in the java.util.Formatter class.

      Specification

      The API changes for ValueTree and DocTreeScanner are given in the attached spec diff. The latest version is available here.

      The tag specification is amended to allow an optional format string:

      • {@value format _package_.class#field }

      The format string may be omitted, in which case a default format will be used, appropriate to the type of the field. If the format string is given, it must either begin with a percent character (%) or be enclosed in double-quote characters ("). It must contain exactly one percent character. The string must conform to the definition of a format string, as specified in the documentation for java.util.Formatter. The conversion specified in the format string must be appropriate for the type of the constant.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              darcy Joe Darcy
              Reviewed By:
              Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: