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

[Fmt-*] Clarify DecimalFormat description of FieldPosition use

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 10
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Clarify handling of the FieldPosition settings in the java.text.Format APIs.

      Problem

      The java.text.Format subclasses, such as DecimalFormat, typically explains the FieldPosition argument as follows.

      public final StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)

      pos - On input: an alignment field, if desired. On output: the offsets of the alignment field.

      This description appears to be confusing. The developers may think that 'pos' can take the offset values specifying the position where the formatted text of the given field should be stored. But in actual, 'pos' is used only for getting information of the position where the formatted text of the given field has actually been stored.

      In addition to this argument description problem, the format method tends to miss @return descriptions. And some just say "Formats a time object to a time string", which should mention that the formatted string is appended to the given StringBuffer.

      Solution

      Clarify the FieldPosition argument description of the format method in Format, DecimalFormat, MessageFormat, DateFormat, and SimpleDateFormat, if applicable.

      Add any missing @return descriptions to the method.

      Clarify method descriptions, such as the append-to-StringBuffer operation.

      Specification

      Specdiff: http://cr.openjdk.java.net/~nishjain/6354947/specdiff/specdiff.02/overview-summary.html

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                nishjain Nishit Jain
                Reporter:
                gmanwanisunw Girish Manwani (Inactive)
                Reviewed By:
                Naoto Sato
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: