Polish Javadoc for converters

spring-core/src/main/java/org/springframework/core/convert/converter/ConditionalGenericConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -21,7 +21,8 @@ import org.springframework.core.convert.TypeDescriptor;
 /**
  * A {@link GenericConverter} that may conditionally execute based on attributes
  * of the {@code source} and {@code target} {@link TypeDescriptor}.
- * See {@link ConditionalConverter} for details.
+ *
+ * <p>See {@link ConditionalConverter} for details.
  *
  * @author Keith Donald
  * @author Phillip Webb

spring-core/src/main/java/org/springframework/core/convert/converter/Converter.java

@@ -17,23 +17,24 @@
 package org.springframework.core.convert.converter;
 
 /**
- * A converter converts a source object of type S to a target of type T.
- * Implementations of this interface are thread-safe and can be shared.
+ * A converter converts a source object of type {@code S} to a target of type {@code T}.
+ *
+ * <p>Implementations of this interface are thread-safe and can be shared.
  *
  * <p>Implementations may additionally implement {@link ConditionalConverter}.
  *
  * @author Keith Donald
  * @since 3.0
- * @param <S> The source type
- * @param <T> The target type
+ * @param <S> the source type
+ * @param <T> the target type
  */
 public interface Converter<S, T> {
 
 	/**
-	 * Convert the source of type S to target type T.
-	 * @param source the source object to convert, which must be an instance of S (never {@code null})
-	 * @return the converted object, which must be an instance of T (potentially {@code null})
-	 * @throws IllegalArgumentException if the source could not be converted to the desired target type
+	 * Convert the source object of type {@code S} to target type {@code T}.
+	 * @param source the source object to convert, which must be an instance of {@code S} (never {@code null})
+	 * @return the converted object, which must be an instance of {@code T} (potentially {@code null})
+	 * @throws IllegalArgumentException if the source cannot be converted to the desired target type
 	 */
 	T convert(S source);
 

spring-core/src/main/java/org/springframework/core/convert/converter/GenericConverter.java

@@ -29,10 +29,10 @@ import org.springframework.util.Assert;
  * type pairs (see {@link #getConvertibleTypes()}. In addition, GenericConverter implementations
  * have access to source/target {@link TypeDescriptor field context} during the type conversion
  * process. This allows for resolving source and target field metadata such as annotations and
- * generics information, which can be used influence the conversion logic.
+ * generics information, which can be used to influence the conversion logic.
  *
  * <p>This interface should generally not be used when the simpler {@link Converter} or
- * {@link ConverterFactory} interfaces are sufficient.
+ * {@link ConverterFactory} interface is sufficient.
  *
  * <p>Implementations may additionally implement {@link ConditionalConverter}.
  *
@@ -47,16 +47,16 @@ import org.springframework.util.Assert;
 public interface GenericConverter {
 
 	/**
-	 * Return the source and target types which this converter can convert between. Each
-	 * entry is a convertible source-to-target type pair.
-	 * <p>For {@link ConditionalConverter conditional} converters this method may return
+	 * Return the source and target types that this converter can convert between.
+	 * <p>Each entry is a convertible source-to-target type pair.
+	 * <p>For {@link ConditionalConverter conditional converters} this method may return
 	 * {@code null} to indicate all source-to-target pairs should be considered.
 	 */
 	Set<ConvertiblePair> getConvertibleTypes();
 
 	/**
-	 * Convert the source to the targetType described by the TypeDescriptor.
-	 * @param source the source object to convert (may be null)
+	 * Convert the source object to the targetType described by the {@code TypeDescriptor}.
+	 * @param source the source object to convert (may be {@code null})
 	 * @param sourceType the type descriptor of the field we are converting from
 	 * @param targetType the type descriptor of the field we are converting to
 	 * @return the converted object

spring-core/src/main/java/org/springframework/core/convert/support/FallbackObjectToStringConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 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,12 +25,15 @@ import org.springframework.core.convert.converter.ConditionalGenericConverter;
 import org.springframework.util.ClassUtils;
 
 /**
- * Simply calls {@link Object#toString()} to convert any supported Object to a String.
- * Supports CharSequence, StringWriter, and any class with a String constructor or
- * {@code valueOf(String)} method.
+ * Simply calls {@link Object#toString()} to convert any supported object
+ * to a {@link String}.
  *
- * <p>Used by the default ConversionService as a fallback if there are no other explicit
- * to-String converters registered.
+ * <p>Supports {@link CharSequence}, {@link StringWriter}, and any class
+ * with a String constructor or one of the following static factory methods:
+ * {@code valueOf(String)}, {@code of(String)}, {@code from(String)}.
+ *
+ * <p>Used by the {@link DefaultConversionService} as a fallback if there
+ * are no other explicit to-String converters registered.
  *
  * @author Keith Donald
  * @author Juergen Hoeller

spring-core/src/main/java/org/springframework/core/convert/support/ObjectToObjectConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -29,14 +29,23 @@ import org.springframework.util.ClassUtils;
 import org.springframework.util.ReflectionUtils;
 
 /**
- * Generic converter that attempts to convert a source Object to a target type
- * by delegating to methods on the target type.
+ * Generic converter that uses conventions to convert a source object to a
+ * {@code targetType} by delegating to a method on the source object or to
+ * a static factory method or constructor on the {@code targetType}.
  *
- * <p>Calls a static {@code valueOf(sourceType)} or Java 8 style {@code of|from(sourceType)}
- * method on the target type to perform the conversion, if such a method exists. Otherwise,
- * it checks for a {@code to[targetType.simpleName]} method on the source type calls
- * the target type's constructor that accepts a single {@code sourceType} argument, if such
- * a constructor exists. If neither strategy works, it throws a ConversionFailedException.
+ * <h3>Conversion Algorithm</h3>
+ * <ol>
+ * <li>Invoke a {@code to[targetType.simpleName]()} method on the source object
+ * that has a return type equal to {@code targetType}, if such a method exists.
+ * For example, {@code org.example.Bar Foo#toBar()} is a method that follows this
+ * convention.
+ * <li>Otherwise invoke a <em>static</em> {@code valueOf(sourceType)} or Java
+ * 8 style <em>static</em> {@code of(sourceType)} or {@code from(sourceType)}
+ * method on the {@code targetType}, if such a method exists.
+ * <li>Otherwise invoke a constructor on the {@code targetType} that accepts
+ * a single {@code sourceType} argument, if such a constructor exists.
+ * <li>Otherwise throw a {@link ConversionFailedException}.
+ * </ol>
  *
  * @author Keith Donald
  * @author Juergen Hoeller