Fix recent javadoc errors

Issue: SPR-17174

spring-web/src/main/java/org/springframework/http/client/OkHttp3ClientHttpRequestFactory.java

@@ -71,9 +71,8 @@ public class OkHttp3ClientHttpRequestFactory
 
 
 	/**
-	 * Sets the underlying read timeout in milliseconds.
+	 * Set the underlying read timeout in milliseconds.
 	 * A value of 0 specifies an infinite timeout.
-	 * @see OkHttpClient.Builder#readTimeout(long, TimeUnit)
 	 */
 	public void setReadTimeout(int readTimeout) {
 		this.client = this.client.newBuilder()
@@ -82,9 +81,8 @@ public class OkHttp3ClientHttpRequestFactory
 	}
 
 	/**
-	 * Sets the underlying write timeout in milliseconds.
+	 * Set the underlying write timeout in milliseconds.
 	 * A value of 0 specifies an infinite timeout.
-	 * @see OkHttpClient.Builder#writeTimeout(long, TimeUnit)
 	 */
 	public void setWriteTimeout(int writeTimeout) {
 		this.client = this.client.newBuilder()
@@ -93,9 +91,8 @@ public class OkHttp3ClientHttpRequestFactory
 	}
 
 	/**
-	 * Sets the underlying connect timeout in milliseconds.
+	 * Set the underlying connect timeout in milliseconds.
 	 * A value of 0 specifies an infinite timeout.
-	 * @see OkHttpClient.Builder#connectTimeout(long, TimeUnit)
 	 */
 	public void setConnectTimeout(int connectTimeout) {
 		this.client = this.client.newBuilder()

spring-web/src/main/java/org/springframework/http/client/reactive/ReactorClientHttpConnector.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.
@@ -53,7 +53,7 @@ public class ReactorClientHttpConnector implements ClientHttpConnector {
 
 	/**
 	 * Create a Reactor Netty {@link ClientHttpConnector} with the given
-	 * {@link HttpClientOptions.Builder}
+	 * {@code HttpClientOptions.Builder}
 	 */
 	public ReactorClientHttpConnector(Consumer<? super HttpClientOptions.Builder> clientOptions) {
 		this.httpClient = HttpClient.create(clientOptions);

spring-web/src/main/java/org/springframework/http/converter/protobuf/ProtobufJsonFormatHttpMessageConverter.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.
@@ -41,7 +41,7 @@ public class ProtobufJsonFormatHttpMessageConverter extends ProtobufHttpMessageC
 
 	/**
 	 * Construct a new {@code ProtobufJsonFormatHttpMessageConverter} with default
-	 * {@link JsonFormat.Parser} and {@link JsonFormat.Printer} configuration.
+	 * {@code JsonFormat.Parser} and {@code JsonFormat.Printer} configuration.
 	 */
 	public ProtobufJsonFormatHttpMessageConverter() {
 		this(null,  null, null);
@@ -49,7 +49,7 @@ public class ProtobufJsonFormatHttpMessageConverter extends ProtobufHttpMessageC
 
 	/**
 	 * Construct a new {@code ProtobufJsonFormatHttpMessageConverter} with the given
-	 * {@link JsonFormat.Parser} and {@link JsonFormat.Printer} configuration.
+	 * {@code JsonFormat.Parser} and {@code JsonFormat.Printer} configuration.
 	 * @param parser the JSON parser configuration
 	 * @param printer the JSON printer configuration
 	 */
@@ -61,8 +61,8 @@ public class ProtobufJsonFormatHttpMessageConverter extends ProtobufHttpMessageC
 
 	/**
 	 * Construct a new {@code ProtobufJsonFormatHttpMessageConverter} with the given
-	 * {@link JsonFormat.Parser} and {@link JsonFormat.Printer} configuration, also
-	 * accepting an initializer that allows the registration of message extensions
+	 * {@code JsonFormat.Parser} and {@code JsonFormat.Printer} configuration, also
+	 * accepting an initializer that allows the registration of message extensions.
 	 * @param parser the JSON parser configuration
 	 * @param printer the JSON printer configuration
 	 * @param registryInitializer an initializer for message extensions

spring-web/src/main/java/org/springframework/http/server/reactive/HttpHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -24,16 +24,16 @@ import reactor.core.publisher.Mono;
  *
  * <p>Higher-level, but still generic, building blocks for applications such as
  * {@code WebFilter}, {@code WebSession}, {@code ServerWebExchange}, and others
- * are available in the {@link org.springframework.web.server} package.
+ * are available in the {@code org.springframework.web.server} package.
  *
  * <p>Application level programming models such as annotated controllers and
  * functional handlers are available in the {@code spring-webflux} module.
  *
  * <p>Typically an {@link HttpHandler} represents an entire application with
  * higher-level programming models bridged via
- * {@link org.springframework.web.server.adapter.WebHttpHandlerBuilder
- * WebHttpHandlerBuilder}. Multiple applications at unique context paths can be
- * plugged in with the help of the {@link ContextPathCompositeHandler}.
+ * {@link org.springframework.web.server.adapter.WebHttpHandlerBuilder}.
+ * Multiple applications at unique context paths can be plugged in with the
+ * help of the {@link ContextPathCompositeHandler}.
  *
  * @author Arjen Poutsma
  * @author Rossen Stoyanchev

spring-web/src/main/java/org/springframework/web/client/DefaultResponseErrorHandler.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.
@@ -55,8 +55,8 @@ public class DefaultResponseErrorHandler implements ResponseErrorHandler {
 	/**
 	 * Template method called from {@link #hasError(ClientHttpResponse)}.
 	 * <p>The default implementation checks if the given status code is
-	 * {@link HttpStatus.Series#CLIENT_ERROR CLIENT_ERROR} or
-	 * {@link HttpStatus.Series#SERVER_ERROR SERVER_ERROR}.
+	 * {@code HttpStatus.Series#CLIENT_ERROR CLIENT_ERROR} or
+	 * {@code HttpStatus.Series#SERVER_ERROR SERVER_ERROR}.
 	 * Can be overridden in subclasses.
 	 * @param statusCode the HTTP status code
 	 * @return {@code true} if the response has an error; {@code false} otherwise
@@ -101,7 +101,6 @@ public class DefaultResponseErrorHandler implements ResponseErrorHandler {
 		}
 	}
 
-
 	/**
 	 * Determine the HTTP status of the given response.
 	 * @param response the response to inspect

spring-web/src/main/java/org/springframework/web/client/ExtractingResponseErrorHandler.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.
@@ -29,25 +29,25 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.CollectionUtils;
 
 /**
- * Implementation of {@link ResponseErrorHandler} that uses {@link HttpMessageConverter}s to
- * convert HTTP error responses to {@link RestClientException}.
+ * Implementation of {@link ResponseErrorHandler} that uses {@link HttpMessageConverter}s
+ * to convert HTTP error responses to {@link RestClientException}.
  *
  * <p>To use this error handler, you must specify a
  * {@linkplain #setStatusMapping(Map) status mapping} and/or a
  * {@linkplain #setSeriesMapping(Map) series mapping}. If either of these mappings has a match
  * for the {@linkplain ClientHttpResponse#getStatusCode() status code} of a given
  * {@code ClientHttpResponse}, {@link #hasError(ClientHttpResponse)} will return
- * {@code true} and {@link #handleError(ClientHttpResponse)} will attempt to use the
+ * {@code true}, and {@link #handleError(ClientHttpResponse)} will attempt to use the
  * {@linkplain #setMessageConverters(List) configured message converters} to convert the response
  * into the mapped subclass of {@link RestClientException}. Note that the
  * {@linkplain #setStatusMapping(Map) status mapping} takes precedence over
  * {@linkplain #setSeriesMapping(Map) series mapping}.
  *
  * <p>If there is no match, this error handler will default to the behavior of
- * {@link DefaultResponseErrorHandler}. Note that you can override this default behavior by
- * specifying a {@linkplain #setSeriesMapping(Map) series mapping} from
- * {@link HttpStatus.Series#CLIENT_ERROR} and/or {@link HttpStatus.Series#SERVER_ERROR} to
- * {@code null}.
+ * {@link DefaultResponseErrorHandler}. Note that you can override this default behavior
+ * by specifying a {@linkplain #setSeriesMapping(Map) series mapping} from
+ * {@code HttpStatus.Series#CLIENT_ERROR} and/or {@code HttpStatus.Series#SERVER_ERROR}
+ * to {@code null}.
  *
  * @author Simon Galperin
  * @author Arjen Poutsma

spring-web/src/main/java/org/springframework/web/client/RestOperations.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.
@@ -657,7 +657,7 @@ public interface RestOperations {
 			throws RestClientException;
 
 
-	// general execution
+	// General execution
 
 	/**
 	 * Execute the HTTP method to the given URI template, preparing the request with the

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

@@ -69,11 +69,11 @@ import org.springframework.web.util.UriTemplateHandler;
  * support of less frequent cases.
  *
  * <p><strong>NOTE:</strong> As of 5.0, the non-blocking, reactive
- * {@link org.springframework.web.reactive.client.WebClient WebClient} offers a
+ * {@code org.springframework.web.reactive.client.WebClient} offers a
  * modern alternative to the {@code RestTemplate} with efficient support for
  * both sync and async, as well as streaming scenarios. The {@code RestTemplate}
  * will be deprecated in a future version and will not have major new features
- * gong forward.
+ * added going forward.
  *
  * @author Arjen Poutsma
  * @author Brian Clozel
@@ -174,7 +174,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 
 	/**
 	 * Create a new instance of the {@link RestTemplate} based on the given {@link ClientHttpRequestFactory}.
-	 * @param requestFactory HTTP request factory to use
+	 * @param requestFactory the HTTP request factory to use
 	 * @see org.springframework.http.client.SimpleClientHttpRequestFactory
 	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 */
@@ -185,7 +185,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 
 	/**
 	 * Create a new instance of the {@link RestTemplate} using the given list of
-	 * {@link HttpMessageConverter} to use
+	 * {@link HttpMessageConverter} to use.
 	 * @param messageConverters the list of {@link HttpMessageConverter} to use
 	 * @since 3.2.7
 	 */
@@ -633,7 +633,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	}
 
 
-	// general execution
+	// General execution
 
 	@Override
 	@Nullable
@@ -732,39 +732,43 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	}
 
 	/**
-	 * Returns a request callback implementation that prepares the request {@code Accept}
-	 * headers based on the given response type and configured
-	 * {@linkplain #getMessageConverters() message converters}.
+	 * Return a {@code RequestCallback} that sets the request {@code Accept}
+	 * header based on the given response type, cross-checked against the
+	 * configured message converters.
 	 */
 	protected <T> RequestCallback acceptHeaderRequestCallback(Class<T> responseType) {
 		return new AcceptHeaderRequestCallback(responseType);
 	}
 
 	/**
-	 * Returns a request callback implementation that writes the given object to the
-	 * request stream.
+	 * Return a {@code RequestCallback} implementation that writes the given
+	 * object to the request stream.
 	 */
 	protected <T> RequestCallback httpEntityCallback(@Nullable Object requestBody) {
 		return new HttpEntityRequestCallback(requestBody);
 	}
 
 	/**
-	 * Returns a request callback implementation that writes the given object to the
-	 * request stream.
+	 * Return a {@code RequestCallback} implementation that:
+	 * <ol>
+	 * <li>Sets the request {@code Accept} header based on the given response
+	 * type, cross-checked against the configured message converters.
+	 * <li>Writes the given object to the request stream.
+	 * </ol>
 	 */
 	protected <T> RequestCallback httpEntityCallback(@Nullable Object requestBody, Type responseType) {
 		return new HttpEntityRequestCallback(requestBody, responseType);
 	}
 
 	/**
-	 * Returns a response extractor for {@link ResponseEntity}.
+	 * Return a {@code ResponseExtractor} that prepares a {@link ResponseEntity}.
 	 */
 	protected <T> ResponseExtractor<ResponseEntity<T>> responseEntityExtractor(Type responseType) {
 		return new ResponseEntityResponseExtractor<>(responseType);
 	}
 
 	/**
-	 * Returns a response extractor for {@link HttpHeaders}.
+	 * Return a response extractor for {@link HttpHeaders}.
 	 */
 	protected ResponseExtractor<HttpHeaders> headersExtractor() {
 		return this.headersExtractor;