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

[Fmt-*] Clarify DecimalFormat description of FieldPosition use

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 10
    • core-libs
    • None
    • minimal
    • Java API
    • 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

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

              Dates

                Created:
                Updated:
                Resolved: