Minor Javadoc cleanup (spring-projects#401)

Nothing major found--mostly just polish.

Author: fifthposition

spring-cloud-commons/src/main/java/org/springframework/cloud/client/DefaultServiceInstance.java

@@ -64,9 +64,9 @@ public Map<String, String> getMetadata() {
 	}
 
 	/**
-	 * Create a uri from the given ServiceInstance's host:port
+	 * Creates a URI from the given ServiceInstance's host:port.
 	 * @param instance
-	 * @return URI of the form (secure)?https:http + "host:port"
+	 * @return URI of the form (secure)?https:http + "host:port".
 	 */
 	public static URI getUri(ServiceInstance instance) {
 		String scheme = (instance.isSecure()) ? "https" : "http";

spring-cloud-commons/src/main/java/org/springframework/cloud/client/ServiceInstance.java

@@ -20,43 +20,43 @@
 import java.util.Map;
 
 /**
- * Represents an instance of a Service in a Discovery System
+ * Represents an instance of a service in a discovery system.
  * @author Spencer Gibb
  */
 public interface ServiceInstance {
 
 	/**
-	 * @return the service id as registered.
+	 * @return The service ID as registered.
 	 */
 	String getServiceId();
 
 	/**
-	 * @return the hostname of the registered ServiceInstance
+	 * @return The hostname of the registered service instance.
 	 */
 	String getHost();
 
 	/**
-	 * @return the port of the registered ServiceInstance
+	 * @return The port of the registered service instance.
 	 */
 	int getPort();
 
 	/**
-	 * @return if the port of the registered ServiceInstance is https or not
+	 * @return Whether the port of the registered service instance uses HTTPS.
 	 */
 	boolean isSecure();
 
 	/**
-	 * @return the service uri address
+	 * @return The service URI address.
 	 */
 	URI getUri();
 
 	/**
-	 * @return the key value pair metadata associated with the service instance
+	 * @return The key / value pair metadata associated with the service instance.
 	 */
 	Map<String, String> getMetadata();
 
 	/**
-	 * @return the scheme of the instance
+	 * @return The scheme of the service instance.
 	 */
 	default String getScheme() {
 		return null;

spring-cloud-commons/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreakerImportSelector.java

@@ -21,7 +21,7 @@
 import org.springframework.core.annotation.Order;
 
 /**
- * Import a single circuit breaker implementation Configuration
+ * Imports a single circuit breaker implementation configuration.
  * @author Spencer Gibb
  */
 @Order(Ordered.LOWEST_PRECEDENCE - 100)

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java

@@ -21,27 +21,27 @@
 import org.springframework.cloud.client.ServiceInstance;
 
 /**
- * DiscoveryClient represents read operations commonly available to Discovery service such as
- * Netflix Eureka or consul.io
+ * Represents read operations commonly available to discovery services such as Netflix
+ * Eureka or consul.io.
  * @author Spencer Gibb
  */
 public interface DiscoveryClient {
 
 	/**
-	 * A human readable description of the implementation, used in HealthIndicator
-	 * @return the description
+	 * A human-readable description of the implementation, used in HealthIndicator.
+	 * @return The description.
 	 */
 	String description();
 
 	/**
-	 * Get all ServiceInstances associated with a particular serviceId
-	 * @param serviceId the serviceId to query
-	 * @return a List of ServiceInstance
+	 * Gets all ServiceInstances associated with a particular serviceId.
+	 * @param serviceId The serviceId to query.
+	 * @return A List of ServiceInstance.
 	 */
 	List<ServiceInstance> getInstances(String serviceId);
 
 	/**
-	 * @return all known service ids
+	 * @return All known service IDs.
 	 */
 	List<String> getServices();
 

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/composite/CompositeDiscoveryClient.java

@@ -9,8 +9,8 @@
 import org.springframework.cloud.client.discovery.DiscoveryClient;
 
 /**
- * A {@link DiscoveryClient} composed of other Discovery Client's and will delegate the
- * calls to each of them in order
+ * A {@link DiscoveryClient} that is composed of other discovery clients and delegates
+ * calls to each of them in order.
  * 
  * @author Biju Kunjummen
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/composite/CompositeDiscoveryClientAutoConfiguration.java

@@ -10,7 +10,7 @@
 import java.util.List;
 
 /**
- * Auto-configuration for Composite Discovery Client.
+ * Auto-configuration for composite discovery client.
  * 
  * @author Biju Kunjummen
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java

@@ -19,9 +19,9 @@
 import org.springframework.context.ApplicationEvent;
 
 /**
- * Event DiscoveryClient implementation can broadcast if they support heartbeat's from the
- * discovery server. Provides listeners with a basic indication of a state change in the
- * service catalog.
+ * An event that a DiscoveryClient implementation can broadcast if it supports
+ * heartbeats from the discovery server. Provides listeners with a basic indication
+ * of a state change in the service catalog.
  *
  * @author Spencer Gibb
  * @author Dave Syer
@@ -32,11 +32,11 @@ public class HeartbeatEvent extends ApplicationEvent {
 	private final Object state;
 
 	/**
-	 * Create a new event with a source (for example a discovery client) and a value.
+	 * Creates a new event with a source (for example, a discovery client) and a value.
 	 * Neither parameter should be relied on to have specific content or format.
 	 *
-	 * @param source the source of the event
-	 * @param state the value indicating state of the catalog
+	 * @param source The source of the event.
+	 * @param state The value indicating state of the catalog.
 	 */
 	public HeartbeatEvent(Object source, Object state) {
 		super(source);
@@ -45,12 +45,12 @@ public HeartbeatEvent(Object source, Object state) {
 
 	/**
 	 * A value representing the state of the service catalog. The only requirement is that
-	 * it changes when the catalog is updated, so it can be as simple as a version
-	 * conuter, or a hash. Implementations can provide information to help users visualize
+	 * it changes when the catalog is updated; it can be as simple as a version counter or
+   * a hash. Implementations can provide information to help users visualize
 	 * what is going on in the catalog, but users should not rely on the content (since
 	 * the implementation of the underlying discovery might change).
 	 *
-	 * @return A value representing state of the service catalog
+	 * @return A value representing state of the service catalog.
 	 */
 	public Object getValue() {
 		return this.state;

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatMonitor.java

@@ -19,8 +19,8 @@
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
- * Helper class for listeners to the {@link HeartbeatEvent} providing a convenient way to
- * determine if there has been a change in state.
+ * Helper class for listeners to the {@link HeartbeatEvent}, providing a convenient way
+ * to determine if there has been a change in state.
  *
  * @author Dave Syer
  */
@@ -29,8 +29,8 @@ public class HeartbeatMonitor {
 	private AtomicReference<Object> latestHeartbeat = new AtomicReference<>();
 
 	/**
-	 * @param value the latest heartbeat
-	 * @return true if the state changed
+	 * @param value The latest heartbeat.
+	 * @return True if the state changed.
 	 */
 	public boolean update(Object value) {
 		Object last = this.latestHeartbeat.get();

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/InstanceRegisteredEvent.java

@@ -30,9 +30,9 @@ public class InstanceRegisteredEvent<T> extends ApplicationEvent {
 	private T config;
 
 	/**
-	 * Create a new {@link InstanceRegisteredEvent} instance.
-	 * @param source the component that published the event (never {@code null})
-	 * @param config the configuration of the instance
+	 * Creates a new {@link InstanceRegisteredEvent} instance.
+	 * @param source The component that published the event (never {@code null}).
+	 * @param config The configuration of the instance.
 	 */
 	public InstanceRegisteredEvent(Object source, T config) {
 		super(source);

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/ParentHeartbeatEvent.java

@@ -19,8 +19,8 @@
 import org.springframework.context.ApplicationEvent;
 
 /**
- * Heartbeat Event that a Parent ApplicationContext can send to a child Context. Useful,
- * for example, when config server is located via DiscoveryClient, in which case the
+ * Heartbeat event that a parent ApplicationContext can send to a child context. Useful,
+ * for example, when a config server is located via a DiscoveryClient, in which case the
  * {@link HeartbeatEvent} that triggers this event is fired in the parent (bootstrap)
  * context.
  *

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryCompositeHealthIndicator.java

@@ -26,8 +26,8 @@
 import org.springframework.boot.actuate.health.HealthIndicator;
 
 /**
- * Gathers all DiscoveryHealthIndicator's from a DiscoveryClient implementation
- * and aggregates the statuses.
+ * Gathers all instances of DiscoveryHealthIndicator from a DiscoveryClient
+ * implementation and aggregates the statuses.
  * @author Spencer Gibb
  */
 //TODO: do we need this? Can they just be independent HealthIndicators?

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryHealthIndicator.java

@@ -19,15 +19,15 @@
 import org.springframework.boot.actuate.health.Health;
 
 /**
- * A health indicator interface specific for a DiscoveryClient implementation
+ * A health indicator interface specific to a DiscoveryClient implementation.
  * @author Spencer Gibb
  */
 public interface DiscoveryHealthIndicator {
 
 	String getName();
 
 	/**
-	 * @return an indication of health
+	 * @return An indication of health.
 	 */
 	Health health();
 

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClient.java

@@ -23,9 +23,9 @@
 import org.springframework.cloud.client.discovery.DiscoveryClient;
 
 /**
- * DiscoveryClient used when no implementations are found on the classpath
+ * DiscoveryClient used when no implementations are found on the classpath.
  *
- * @deprecated Use {@link org.springframework.cloud.client.discovery.simple.SimpleDiscoveryClient instead}
+ * @deprecated Use {@link org.springframework.cloud.client.discovery.simple.SimpleDiscoveryClient instead}.
  *
  * @author Dave Syer
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClientAutoConfiguration.java

@@ -41,7 +41,7 @@
 /**
  *
  * @deprecated Use
- * {@link org.springframework.cloud.client.discovery.simple.SimpleDiscoveryClientAutoConfiguration instead}
+ * {@link org.springframework.cloud.client.discovery.simple.SimpleDiscoveryClientAutoConfiguration instead}.
  *
  * @author Dave Syer
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/simple/SimpleDiscoveryClient.java

@@ -9,7 +9,7 @@
 
 /**
  * A {@link org.springframework.cloud.client.discovery.DiscoveryClient} that will use the
- * properties file as a source of service instances
+ * properties file as a source of service instances.
  *
  * @author Biju Kunjummen
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/simple/SimpleDiscoveryClientAutoConfiguration.java

@@ -19,7 +19,7 @@
 import java.net.URI;
 
 /**
- * Spring Boot Auto-Configuration for Simple Properties based Discovery Client
+ * Spring Boot auto-configuration for simple properties-based discovery client.
  *
  * @author Biju Kunjummen
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/simple/SimpleDiscoveryProperties.java

@@ -14,7 +14,7 @@
 /**
  * Properties to hold the details of a
  * {@link org.springframework.cloud.client.discovery.DiscoveryClient} service instances
- * for a given service
+ * for a given service.
  *
  * @author Biju Kunjummen
  */
@@ -54,8 +54,8 @@ public void init() {
 	public static class SimpleServiceInstance implements ServiceInstance {
 
 		/**
-		 * The URI of the service instance. Will be parsed to extract the scheme, hos and
-		 * port.
+		 * The URI of the service instance. Will be parsed to extract the scheme, host,
+     * and port.
 		 */
 		private URI uri;
 		private String host;
@@ -68,7 +68,7 @@ public static class SimpleServiceInstance implements ServiceInstance {
 		private Map<String, String> metadata = new LinkedHashMap<>();
 		/**
 		 * The identifier or name for the service. Multiple instances might share the same
-		 * service id.
+		 * service ID.
 		 */
 		private String serviceId;
 

spring-cloud-commons/src/main/java/org/springframework/cloud/client/hypermedia/CloudHypermediaAutoConfiguration.java

@@ -29,8 +29,8 @@
 import org.springframework.context.annotation.Configuration;
 
 /**
- * Registers a default {@link RemoteResourceRefresher} if at least one {@link RemoteResource} is declared in the system
- * and applies verification timings defined in the application properties.
+ * Registers a default {@link RemoteResourceRefresher} if at least one {@link RemoteResource} is declared in the system.
+ * Applies verification timings defined in the application properties.
  * 
  * @author Oliver Gierke
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/hypermedia/DiscoveredResource.java

@@ -53,7 +53,7 @@ public DiscoveredResource(ServiceInstanceProvider provider, TraversalDefinition
 	/**
 	 * Configures the {@link RestOperations} to use to execute the traversal and verifying HEAD calls.
 	 * 
-	 * @param restOperations can be {@literal null}, resorting to a default {@link RestTemplate} in that case.
+	 * @param restOperations Can be {@literal null}; resorts to a default {@link RestTemplate} in that case.
 	 */
 	public void setRestOperations(RestOperations restOperations) {
 		this.restOperations = restOperations == null ? new RestTemplate() : restOperations;
@@ -81,7 +81,7 @@ public void setLink(Link link) {
 	}
 
 	/**
-	 * Verifies the link to the current
+	 * Verifies the link to the current.
 	 */
 	public void verifyOrDiscover() {
 		this.link = link == null ? discoverLink() : verify(link);
@@ -90,7 +90,7 @@ public void verifyOrDiscover() {
 	/**
 	 * Verifies the given {@link Link} by issuing an HTTP HEAD request to the resource.
 	 * 
-	 * @param link must not be {@literal null}.
+	 * @param link Must not be {@literal null}.
 	 * @return
 	 */
 	private Link verify(Link link) {

spring-cloud-commons/src/main/java/org/springframework/cloud/client/hypermedia/DynamicServiceInstanceProvider.java

@@ -21,7 +21,7 @@
 import org.springframework.cloud.client.discovery.DiscoveryClient;
 
 /**
- * {@link ServiceInstanceProvider} to work with a {@link DiscoveryClient} to lookup a service by name. Will pick the
+ * {@link ServiceInstanceProvider} to work with a {@link DiscoveryClient} to look up a service by name. Picks the
  * first one returned by the configured {@link DiscoveryClient}.
  * 
  * @author Oliver Gierke

spring-cloud-commons/src/main/java/org/springframework/cloud/client/hypermedia/RemoteResource.java

@@ -25,15 +25,15 @@
 public interface RemoteResource {
 
 	/**
-	 * Returns the {@link Link} to the resource in case it is available or {@literal null}
-	 * in case it's gone, i.e. either generally unavailable or can't be discovered.
+	 * Returns the {@link Link} to the resource if it is available, or {@literal null}
+	 * if it is gone (i.e. it either is generally unavailable or can't be discovered).
 	 */
 	Link getLink();
 
 	/**
-	 * Discovers the the resource in case it hasn't been yet or became unavailable. In
-	 * case a link has been discovered previously, it is verified and either confirmed or
-	 * the link is removed to indicate it's not available anymore.
+	 * Discovers the resource if it hasn't been discovered yet or has become
+   * unavailable. If a link has been discovered previously, it is verified and either
+   * confirmed or removed to indicate that it's not available anymore.
 	 */
 	void verifyOrDiscover();
 }

spring-cloud-commons/src/main/java/org/springframework/cloud/client/hypermedia/RemoteResourceRefresher.java

@@ -22,7 +22,7 @@
 import org.springframework.scheduling.config.ScheduledTaskRegistrar;
 
 /**
- * A {@link ScheduledTaskRegistrar} that verifies all {@link DiscoveredResource} instances in the system based
+ * A {@link ScheduledTaskRegistrar} that verifies all {@link DiscoveredResource} instances in the system, based
  * on the given timing configuration.
  * 
  * @author Oliver Gierke