polish

org.springframework.context/src/main/java/org/springframework/format/annotation/DateTimeFormat.java

@@ -22,7 +22,7 @@ import java.lang.annotation.Target;
 
 /**
  * Declares that a field should be formatted as a date time.
- * Supports formatting by style pattern, custom format pattern string, or ISO date time pattern.
+ * Supports formatting by style pattern, ISO date time pattern, or custom format pattern string.
  * Can be applied to <code>java.util.Date</code>, <code>java.util.Calendar</code>, <code>java.long.Long</code>, or Joda Time fields.
  * <p>
  * For style-based formatting, set the {@link #style()} attribute to be the style pattern code.  
@@ -30,9 +30,9 @@ import java.lang.annotation.Target;
  * Specify a character of 'S' for short style, 'M' for medium, 'L' for long, and 'F' for full.
  * A date or time may be omitted by specifying the style character '-'.
  * <p>
- * For pattern-based formatting, set the {@link #pattern()} attribute to be the DateTime pattern, such as <code>yyyy/mm/dd h:mm:ss a</code>.
- * <p>
  * For ISO-based formatting, set the {@link #iso()} attribute to be the desired {@link ISO} format, such as {@link ISO#DATE}.
+   <p>
+ * For custom formatting, set the {@link #pattern()} attribute to be the DateTime pattern, such as <code>yyyy/mm/dd h:mm:ss a</code>.
  * <p>
  * Each attribute is mutually exclusive, so only set one attribute per annotation instance (the one most convenient one for your formatting needs).
  * When the pattern attribute is specified, it takes precedence over both the style and ISO attribute.
@@ -50,21 +50,25 @@ public @interface DateTimeFormat {
 	/**
 	 * The style pattern to use to format the field.
 	 * Defaults to 'SS' for short date time.
+	 * Set this attribute when you wish to format your field in accordance with a common style other than the default style.
 	 */
 	String style() default "SS";
 
 	/**
-	 * Set this attribute or the style attribute, not both.
-	 */
-	String pattern() default "";
-
-	/**
-	 * A ISO pattern to apply to format the field.
+	 * The ISO pattern to use to format the field.
 	 * The possible ISO patterns are defined in the {@link ISO} enum.
 	 * Defaults to ISO.NONE, indicating this attribute should be ignored.
+	 * Set this attribute when you wish to format your field in accordance with an ISO date time format.
 	 */
 	ISO iso() default ISO.NONE;
 
+	/**
+	 * The custom pattern to use to format the field.
+	 * Defaults to empty String, indicating no custom pattern String has been specified.
+	 * Set this attribute when you wish to format your field in accordance with a custom date time pattern not represented by a style or ISO format.
+	 */
+	String pattern() default "";
+
 	/**
 	 * Common ISO date time format patterns.
 	 * @author Keith Donald