javadoc polishing

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

@@ -22,6 +22,18 @@ import java.lang.annotation.Target;
 
 /**
  * Declares that a field should be formatted as a date time.
+ * Supports formatting by {@link Style} or by pattern string.
+ * <p>
+ * For style-based formatting:
+ * <ul>
+ * <li>Set <code>dateStyle</code> attribute to specify the style of the <i>date</i> portion of the DateTime.
+ * <li>Set <code>timeStyle</code> attribute to specify the style of the <i>time</i> portion of the DateTime.
+ * <li>The default for both dateStyle and timeStyle if not specified is {@link Style#NONE}.
+ * </ul>
+ * For pattern-based formatting, set the <code>pattern</code> attribute to be the DateTime pattern, such as <code>yyyy/mm/dd h:mm:ss a</code>.
+ * <p>
+ * If no annotation attributes are specified, the default format applied is style-based with dateStyle={@link Style#SHORT} and timeStyle={@link Style#SHORT}.
+ * 
  * @author Keith Donald
  * @since 3.0
  */
@@ -51,26 +63,58 @@ public @interface DateTimeFormat {
 	 * Supported DateTimeFormat styles.
 	 */
 	public enum Style {
+		
+		/**
+		 * The short format style.
+		 * <br>Example short dateStyle: Locale.US="M/d/yy" e.g. 10/31/2009
+		 * <br>Example short timeStyle: Locale.US="h:mm a" e.g. 1:30 PM
+		 */
 		SHORT {
 			public String toString() {
 				return "S";
 			}
 		},
+		
+		/**
+		 * The medium format style.
+		 * <br>Example medium dateStyle: Locale.US="MMM d, yyyy" e.g Oct 31, 2009
+		 * <br>Example medium timeStyle: Locale.US="h:mm:ss a" e.g. 1:30:00 PM
+		 */
 		MEDIUM {
 			public String toString() {
 				return "M";
 			}
 		},
+
+		/**
+		 * The long format style.
+		 * <br>Example long dateStyle: Locale.US="MMMM d, yyyy" e.g October 31, 2009
+		 * <br>Example long timeStyle: Locale.US="h:mm:ss a z" e.g. 1:30:00 PM Eastern Standard Time  
+		 */
 		LONG {
 			public String toString() {
 				return "L";
 			}
 		},
+
+		/**
+		 * The full format style.
+		 * <br>Example full dateStyle: Locale.US="EEEE, MMMM d, yyyy" e.g. Saturday, October 31, 2009
+		 * <br>Example full timeStyle: Locale.US="h:mm:ss a z" e.g 1:30:00 PM Eastern Standard Time
+		 */
 		FULL {
 			public String toString() {
 				return "F";
 			}
 		},
+
+		/**
+		 * The none format style.
+		 * A dateStyle specified with this value results in date fields such as mm, dd, and yyyy being ignored.
+		 * A timeStyle specified with this value results in time fields such as hh, mm being ignored.
+		 * If both dateStyle and timeStyle are set to this value and the pattern attribute is also not specified,
+		 * a default value for each is selected based on the type of field being annotated.
+		 */
 		NONE {
 			public String toString() {
 				return "-";

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

@@ -29,10 +29,29 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ISODateTimeFormat {
 
-	Style value();
+	/**
+	 * The ISO style to use to format the date time.
+	 * Defaults to {@link Style#DATE_TIME}.
+	 */
+	Style value() default Style.DATE_TIME;
 
 	public enum Style {
-		DATE, TIME, DATE_TIME
+		
+		/** 
+		 * The most common ISO Date Format <code>yyyy-MM-dd</code> e.g. 2000-10-31.
+		 */
+		DATE,
+
+		/** 
+		 * The most common ISO Time Format <code>hh:mm:ss.SSSZ</code> e.g. 01:30:00.000-05:00.
+		 */
+		TIME,
+
+		/** 
+		 * The most common ISO DateTime Format <code>yyyy-MM-dd'T'hh:mm:ss.SSSZ</code> e.g. 2000-10-31 01:30:00.000-05:00.
+		 * The default if no annotation value is specified.
+		 */
+		DATE_TIME
 	}
 
 }

org.springframework.context/src/main/java/org/springframework/format/datetime/joda/DateTimeFormatAnnotationFormatterFactory.java

@@ -34,7 +34,11 @@ public final class DateTimeFormatAnnotationFormatterFactory extends AbstractDate
 		} else {
 			Style dateStyle = annotation.dateStyle();
 			Style timeStyle = annotation.timeStyle();
-			return forDateTimeStyle(dateStyle, timeStyle);
+			if (Style.NONE == dateStyle && Style.NONE == timeStyle) {
+				return forDateTimeStyle(Style.SHORT, Style.SHORT);
+			} else {
+				return forDateTimeStyle(dateStyle, timeStyle);
+			}
 		}
 	}
 

org.springframework.context/src/test/java/org/springframework/format/datetime/joda/JodaTimeFormattingTests.java

@@ -19,7 +19,6 @@ import org.springframework.context.i18n.LocaleContextHolder;
 import org.springframework.format.annotation.DateTimeFormat;
 import org.springframework.format.annotation.ISODateTimeFormat;
 import org.springframework.format.annotation.DateTimeFormat.Style;
-import org.springframework.format.datetime.joda.JodaTimeFormattingConfigurer;
 import org.springframework.format.support.FormattingConversionService;
 import org.springframework.validation.DataBinder;
 
@@ -49,6 +48,14 @@ public class JodaTimeFormattingTests {
 		JodaTimeContextHolder.setJodaTimeContext(null);
 	}
 
+	@Test
+	public void testJodaTimePatternsForStyle() {
+		System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("SS", LocaleContextHolder.getLocale()));
+		System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("MM", LocaleContextHolder.getLocale()));
+		System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("LL", LocaleContextHolder.getLocale()));
+		System.out.println(org.joda.time.format.DateTimeFormat.patternForStyle("FF", LocaleContextHolder.getLocale()));
+	}
+	
 	@Test
 	public void testBindLocalDate() {
 		MutablePropertyValues propertyValues = new MutablePropertyValues();