ICU-9250 (J) Document that date format S+ fields truncate for S,SS and zero-pad for SSSS+

X-SVN-Rev: 32647

icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java

@@ -218,6 +218,14 @@ public abstract class DateFormat extends UFormat {
     /**
      * {@icu} FieldPosition selector for 'S' field alignment,
      * corresponding to the {@link Calendar#MILLISECOND} field.
+     *
+     * Note: Time formats that use 'S' can display a maximum of three
+     * significant digits for fractional seconds, corresponding to millisecond
+     * resolution and a fractional seconds sub-pattern of SSS. If the
+     * sub-pattern is S or SS, the fractional seconds value will be truncated
+     * (not rounded) to the number of display places specified. If the
+     * fractional seconds sub-pattern is longer than SSS, the additional
+     * display places will be filled with zeros.
      * @stable ICU 3.0
      */
     public final static int FRACTIONAL_SECOND_FIELD = 8;

icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java

@@ -81,6 +81,7 @@ import com.ibm.icu.util.ULocale.Category;
  * m        minute in hour          (Number)            30
  * s        second in minute        (Number)            55
  * S        fractional second       (Number)            978
+ *          (maximum resolution of SSS; truncated if shorter, zero-padded if longer)
  * E        day of week             (Text)              Tuesday
  * e*       day of week (local 1~7) (Text & Number)     Tuesday & 2
  * D        day in year             (Number)            189