Polishing

spring-core/src/main/java/org/springframework/util/StringUtils.java

@@ -800,15 +800,19 @@ public abstract class StringUtils {
 	}
 
 	/**
-	 * Decode the given encoded URI component value by replacing "<i>{@code %xy}</i>" sequences
-	 * by an hexadecimal representation of the character in the specified charset, letting other
-	 * characters unchanged.
-	 * @param source the encoded {@code String}
-	 * @param charset the character encoding to use to decode the "<i>{@code %xy}</i>" sequences
+	 * Decode the given encoded URI component value by replacing each
+	 * "<i>{@code %xy}</i>" sequence with a hexadecimal representation of the
+	 * character in the specified character encoding, leaving other characters
+	 * unmodified.
+	 * @param source the encoded URI component value
+	 * @param charset the character encoding to use to decode the "<i>{@code %xy}</i>"
+	 * sequences
 	 * @return the decoded value
-	 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
+	 * @throws IllegalArgumentException if the given source contains invalid encoded
+	 * sequences
 	 * @since 5.0
-	 * @see java.net.URLDecoder#decode(String, String) java.net.URLDecoder#decode for HTML form decoding
+	 * @see java.net.URLDecoder#decode(String, String) java.net.URLDecoder#decode
+	 * for HTML form decoding
 	 */
 	public static String uriDecode(String source, Charset charset) {
 		int length = source.length();

spring-web/src/main/java/org/springframework/web/client/ApiVersionInserter.java

@@ -30,17 +30,19 @@ import org.springframework.http.HttpHeaders;
 public interface ApiVersionInserter {
 
 	/**
-	 * Allows inserting the version into the URI.
+	 * Insert the version into the URI.
+	 * <p>The default implementation returns the supplied URI unmodified.
 	 * @param version the version to insert
 	 * @param uri the URI for the request
-	 * @return the updated or the same URI
+	 * @return the updated URI, or the original URI unmodified
 	 */
 	default URI insertVersion(Object version, URI uri) {
 		return uri;
 	}
 
 	/**
-	 * Allows inserting the version into request headers.
+	 * Insert the version into the request headers.
+	 * <p>The default implementation does not modify the supplied headers.
 	 * @param version the version to insert
 	 * @param headers the request headers
 	 */

spring-web/src/main/java/org/springframework/web/service/registry/AnnotationHttpServiceRegistrar.java

@@ -20,7 +20,7 @@ import org.springframework.core.annotation.MergedAnnotation;
 import org.springframework.core.type.AnnotationMetadata;
 
 /**
- * Built-in implementation {@link AbstractHttpServiceRegistrar} that uses
+ * Built-in implementation of {@link AbstractHttpServiceRegistrar} that uses
  * {@link ImportHttpServices} annotations on the importing configuration class
  * to determine the HTTP services and groups to register.
  *

spring-web/src/main/java/org/springframework/web/service/registry/HttpServiceProxyRegistryFactoryBean.java

@@ -44,11 +44,11 @@ import org.springframework.web.service.invoker.HttpServiceProxyFactory;
 
 /**
  * {@link FactoryBean} for {@link HttpServiceProxyRegistry} responsible for
- * initializing {@link HttpServiceGroup}s, and creating the HTTP Service client
+ * initializing {@link HttpServiceGroup}s and creating the HTTP Service client
  * proxies for each group.
  *
  * <p>This class is imported as a bean definition through an
- * {@link AbstractHttpServiceRegistrar}, and given .
+ * {@link AbstractHttpServiceRegistrar}.
  *
  * @author Rossen Stoyanchev
  * @author Phillip Webb

spring-web/src/main/java/org/springframework/web/service/registry/ImportHttpServices.java

@@ -49,11 +49,11 @@ import org.springframework.web.service.annotation.HttpExchange;
  * @see Container
  * @see AbstractHttpServiceRegistrar
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
 @Repeatable(ImportHttpServices.Container.class)
 @Import(AnnotationHttpServiceRegistrar.class)
-@Documented
 public @interface ImportHttpServices {
 
 	/**
@@ -77,8 +77,9 @@ public @interface ImportHttpServices {
 
 	/**
 	 * Detect HTTP Services in the packages of the specified classes by looking
-	 * for interfaces with type or method level
-	 * {@link org.springframework.web.service.annotation.HttpExchange @HttpExchange}.
+	 * for interfaces with type-level or method-level
+	 * {@link org.springframework.web.service.annotation.HttpExchange @HttpExchange}
+	 * annotations.
 	 */
 	Class<?>[] basePackageClasses() default {};
 
@@ -91,7 +92,7 @@ public @interface ImportHttpServices {
 	/**
 	 * Specify the type of client to use for the group.
 	 * <p>By default, this is {@link HttpServiceGroup.ClientType#UNSPECIFIED}
-	 * in which case {@code RestClient} is used, but this default can be reset
+	 * in which case {@code RestClient} is used, but this default can be changed
 	 * via {@link AbstractHttpServiceRegistrar#setDefaultClientType}.
 	 */
 	HttpServiceGroup.ClientType clientType() default HttpServiceGroup.ClientType.UNSPECIFIED;
@@ -99,8 +100,8 @@ public @interface ImportHttpServices {
 
 	/**
 	 * Container annotation that is necessary for the repeatable
-	 * {@link ImportHttpServices} annotation, but does not need to be declared
-	 * in application code.
+	 * {@link ImportHttpServices @ImportHttpServices} annotation, but does not
+	 * need to be declared in application code.
 	 */
 	@Target(ElementType.TYPE)
 	@Retention(RetentionPolicy.RUNTIME)

spring-web/src/main/java/org/springframework/web/util/UriUtils.java

@@ -360,30 +360,39 @@ public abstract class UriUtils {
 
 
 	/**
-	 * Decode the given encoded URI component.
-	 * <p>See {@link StringUtils#uriDecode(String, Charset)} for the decoding rules.
-	 * @param source the encoded String
-	 * @param encoding the character encoding to use
+	 * Decode the given encoded URI component value by replacing each
+	 * "<i>{@code %xy}</i>" sequence with a hexadecimal representation of the
+	 * character in the specified character encoding, leaving other characters
+	 * unmodified.
+	 * @param source the encoded URI component value
+	 * @param encoding the character encoding to use to decode the "<i>{@code %xy}</i>"
+	 * sequences
 	 * @return the decoded value
-	 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
+	 * @throws IllegalArgumentException if the given source contains invalid encoded
+	 * sequences
 	 * @see StringUtils#uriDecode(String, Charset)
-	 * @see java.net.URLDecoder#decode(String, String)
+	 * @see java.net.URLDecoder#decode(String, String) java.net.URLDecoder#decode
+	 * for HTML form decoding
 	 */
 	public static String decode(String source, String encoding) {
 		return StringUtils.uriDecode(source, Charset.forName(encoding));
 	}
 
 	/**
-	 * Decode the given encoded URI component value by replacing "<i>{@code %xy}</i>" sequences
-	 * by an hexadecimal representation of the character in the specified charset, letting other
-	 * characters unchanged.
-	 * @param source the encoded {@code String}
-	 * @param charset the character encoding to use to decode the "<i>{@code %xy}</i>" sequences
+	 * Decode the given encoded URI component value by replacing each
+	 * "<i>{@code %xy}</i>" sequence with a hexadecimal representation of the
+	 * character in the specified character encoding, leaving other characters
+	 * unmodified.
+	 * @param source the encoded URI component value
+	 * @param charset the character encoding to use to decode the "<i>{@code %xy}</i>"
+	 * sequences
 	 * @return the decoded value
-	 * @throws IllegalArgumentException when the given source contains invalid encoded sequences
+	 * @throws IllegalArgumentException if the given source contains invalid encoded
+	 * sequences
 	 * @since 5.0
 	 * @see StringUtils#uriDecode(String, Charset)
-	 * @see java.net.URLDecoder#decode(String, String) java.net.URLDecoder#decode for HTML form decoding
+	 * @see java.net.URLDecoder#decode(String, String) java.net.URLDecoder#decode
+	 * for HTML form decoding
 	 */
 	public static String decode(String source, Charset charset) {
 		return StringUtils.uriDecode(source, charset);