Revised format annotation docs

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,8 +26,8 @@ import java.lang.annotation.Target;
  * Declares that a field or method parameter should be formatted as a date or time.
  *
  * <p>Supports formatting by style pattern, ISO date time pattern, or custom format pattern string.
- * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code java.lang.Long},
- * Joda-Time value types; and as of Spring 4 and JDK 8, to JSR-310 <code>java.time</code> types too.
+ * Can be applied to {@code java.util.Date}, {@code java.util.Calendar}, {@code Long} (for
+ * millisecond timestamps) as well as JSR-310 <code>java.time</code> and Joda-Time value types.
  *
  * <p>For style-based formatting, set the {@link #style} attribute to be the style pattern code.
  * The first character of the code is the date style, and the second character is the time style.
@@ -48,6 +48,7 @@ import java.lang.annotation.Target;
  * @author Keith Donald
  * @author Juergen Hoeller
  * @since 3.0
+ * @see java.time.format.DateTimeFormatter
  * @see org.joda.time.format.DateTimeFormat
  */
 @Documented

spring-context/src/main/java/org/springframework/format/annotation/NumberFormat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,8 +25,8 @@ import java.lang.annotation.Target;
 /**
  * Declares that a field or method parameter should be formatted as a number.
  *
- * <p>Supports formatting by style or custom pattern string.
- * Can be applied to any JDK {@code java.lang.Number} type.
+ * <p>Supports formatting by style or custom pattern string. Can be applied
+ * to any JDK {@code Number} type such as {@code Double} and {@code Long}.
  *
  * <p>For style-based formatting, set the {@link #style} attribute to be the
  * desired {@link Style}. For custom formatting, set the {@link #pattern}

src/docs/asciidoc/core/core-validation.adoc

@@ -363,11 +363,10 @@ the knowledge of how to convert properties to the desired type. For more about
 
 A couple of examples where property editing is used in Spring:
 
-* Setting properties on beans is done by using `PropertyEditor` implementations. When you use
-  `java.lang.String` as the value of a property of some bean that you declare in an XML
-  file, Spring (if the setter of the corresponding property has a
-  `Class` parameter) uses `ClassEditor` to try to resolve the parameter to a `Class`
-  object.
+* Setting properties on beans is done by using `PropertyEditor` implementations.
+  When you use `String` as the value of a property of some bean that you declare
+  in an XML file, Spring (if the setter of the corresponding property has a `Class`
+  parameter) uses `ClassEditor` to try to resolve the parameter to a `Class` object.
 * Parsing HTTP request parameters in Spring's MVC framework is done by using all kinds
   of `PropertyEditor` implementations that you can manually bind in all subclasses of the
   `CommandController`.
@@ -789,8 +788,8 @@ The following listing shows the `StringToInteger` class, which is a typical `Con
 [[core-convert-ConverterFactory-SPI]]
 === Using `ConverterFactory`
 
-When you need to centralize the conversion logic for an entire class hierarchy (for
-example, when converting from String to java.lang.Enum objects), you can implement
+When you need to centralize the conversion logic for an entire class hierarchy
+(for example, when converting from `String` to `Enum` objects), you can implement
 `ConverterFactory`, as the following example shows:
 
 ====
@@ -807,10 +806,10 @@ example, when converting from String to java.lang.Enum objects), you can impleme
 ====
 
 Parameterize S to be the type you are converting from and R to be the base type defining
-the __range__ of classes you can convert to. Then implement getConverter(Class<T>),
+the __range__ of classes you can convert to. Then implement `getConverter(Class<T>)`,
 where T is a subclass of R.
 
-Consider the `StringToEnum` `ConverterFactory` as an example:
+Consider the `StringToEnumConverterFactory` as an example:
 
 ====
 [source,java,indent=0]
@@ -845,13 +844,13 @@ Consider the `StringToEnum` `ConverterFactory` as an example:
 [[core-convert-GenericConverter-SPI]]
 === Using `GenericConverter`
 
-When you require a sophisticated `Converter` implementation, consider using the `GenericConverter`
-interface. With a more flexible but less strongly typed signature than `Converter`, a `GenericConverter`
-supports converting between multiple source and target types. In addition, a
-`GenericConverter` makes available source and target field context that you can use when
-you implement your conversion logic. Such context lets a type conversion be driven
-by a field annotation or by generic information declared on a field signature. The
-following listing shows the interface definition of `GenericConverter`:
+When you require a sophisticated `Converter` implementation, consider using the
+`GenericConverter` interface. With a more flexible but less strongly typed signature
+than `Converter`, a `GenericConverter` supports converting between multiple source and
+target types. In addition, a `GenericConverter` makes available source and target field
+context that you can use when you implement your conversion logic. Such context lets a
+type conversion be driven by a field annotation or by generic information declared on a
+field signature. The following listing shows the interface definition of `GenericConverter`:
 
 ====
 [source,java,indent=0]
@@ -1088,10 +1087,10 @@ directly. To directly address them, Spring 3 introduced a convenient `Formatter`
 provides a simple and robust alternative to `PropertyEditor` implementations for client environments.
 
 In general, you can use the `Converter` SPI when you need to implement general-purpose type
-conversion logic -- for example, for converting between a `java.util.Date` and a
-`java.lang.Long`. You can use the `Formatter` SPI when you work in a client environment (such
-as a web application) and need to parse and print localized field values. The
-`ConversionService` provides a unified type conversion API for both SPIs.
+conversion logic -- for example, for converting between a `java.util.Date` and a `Long`.
+You can use the `Formatter` SPI when you work in a client environment (such as a web
+application) and need to parse and print localized field values. The `ConversionService`
+provides a unified type conversion API for both SPIs.
 
 
 
@@ -1147,7 +1146,7 @@ care to ensure that your `Formatter` implementation is thread-safe.
 
 The `format` subpackages provide several `Formatter` implementations as a convenience.
 The `number` package provides `NumberStyleFormatter`, `CurrencyStyleFormatter`, and
-`PercentStyleFormatter` to format `java.lang.Number` objects that use a `java.text.NumberFormat`.
+`PercentStyleFormatter` to format `Number` objects that use a `java.text.NumberFormat`.
 The `datetime` package provides a `DateFormatter` to format `java.util.Date` objects with
 a `java.text.DateFormat`. The `datetime.joda` package provides comprehensive datetime
 formatting support based on the http://joda-time.sourceforge.net[Joda-Time library].
@@ -1291,8 +1290,9 @@ example shows:
 ==== Format Annotation API
 
 A portable format annotation API exists in the `org.springframework.format.annotation`
-package. You can use `@NumberFormat` to format java.lang.Number fields and `@DateTimeFormat` to
-format `java.util.Date`, `java.util.Calendar`, `java.util.Long`, or Joda-Time fields.
+package. You can use `@NumberFormat` to format `Number` fields such as `Double` and
+`Long`, and `@DateTimeFormat` to format `java.util.Date`, `java.util.Calendar`, `Long`
+(for millisecond timestamps) as well as JSR-310 `java.time` and Joda-Time value types.
 
 The following example uses `@DateTimeFormat` to format a `java.util.Date` as an ISO Date
 (yyyy-MM-dd):
@@ -1316,9 +1316,9 @@ The following example uses `@DateTimeFormat` to format a `java.util.Date` as an
 
 The `FormatterRegistry` is an SPI for registering formatters and converters.
 `FormattingConversionService` is an implementation of `FormatterRegistry` suitable for
-most environments. You can programmatically or declaratively configure this implementation
-as a Spring bean by using `FormattingConversionServiceFactoryBean`. Because
-this implementation also implements `ConversionService`, you can directly configure it
+most environments. You can programmatically or declaratively configure this variant
+as a Spring bean, e.g. by using `FormattingConversionServiceFactoryBean`. Because this
+implementation also implements `ConversionService`, you can directly configure it
 for use with Spring's `DataBinder` and the Spring Expression Language (SpEL).
 
 The following listing shows the `FormatterRegistry` SPI: