--- a/src/java.base/share/classes/java/text/SimpleDateFormat.java Fri Nov 24 14:07:59 2017 +0100
+++ b/src/java.base/share/classes/java/text/SimpleDateFormat.java Thu Nov 30 13:31:30 2017 +0530
@@ -942,8 +942,19 @@
*
* @param date the date-time value to be formatted into a date-time string.
* @param toAppendTo where the new date-time text is to be appended.
- * @param pos the formatting position. On input: an alignment field,
- * if desired. On output: the offsets of the alignment field.
+ * @param pos keeps track on the position of the field within
+ * the returned string. For example, given a date-time text
+ * {@code "1996.07.10 AD at 15:08:56 PDT"}, if the given {@code fieldPosition}
+ * is {@link DateFormat#YEAR_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 0 and 4, respectively.
+ * Notice that if the same date-time field appears more than once in a
+ * pattern, the {@code fieldPosition} will be set for the first occurrence
+ * of that date-time field. For instance, formatting a {@code Date} to the
+ * date-time string {@code "1 PM PDT (Pacific Daylight Time)"} using the
+ * pattern {@code "h a z (zzzz)"} and the alignment field
+ * {@link DateFormat#TIMEZONE_FIELD}, the begin index and end index of
+ * {@code fieldPosition} will be set to 5 and 8, respectively, for the
+ * first occurrence of the timezone pattern character {@code 'z'}.
* @return the formatted date-time string.
* @exception NullPointerException if any of the parameters is {@code null}.
*/