Merge pull request #279 from cescoffier/remove-javadoc-warnings

Improve javadoc and reduce some API visibility

api/src/main/java/io/smallrye/stork/api/Metadata.java

@@ -6,13 +6,14 @@
 
 /**
  * Service Instance metadata.
+ *
  * <p>
  * This class stores service instance metadata that can be used by the load balancer to select the service instance to use.
+ * </p>
  * <p>
  * Instances of this class are <strong>immutable</strong>. Modification operations return new instances.
- * <p>
- * You can creates new instances using the {@link #of(Class)}, {@link #of(Class, Map)} and {@link #with(Enum, Object)}methods.
- * <p>
+ * </p>
+ * You can create new instances using the {@link #of(Class)}, {@link #of(Class, Map)} and {@link #with(Enum, Object)}methods.
  */
 public class Metadata<T extends Enum<T>> {
 
@@ -42,8 +43,10 @@ public static Metadata<? extends MetadataKey> empty() {
     /**
      * Returns an instance of {@link Metadata} containing metadata values.
      *
+     * @param key the class of the key, must not be {@code null}
      * @param metadata the metadata, must not be {@code null}, must not contain {@code null},
      *        must not contain multiple objects of the same class
+     * @param <K> the key type
      * @return the new metadata
      */
     public static <K extends Enum<K> & MetadataKey> Metadata<K> of(Class<K> key, Map<K, Object> metadata) {
@@ -57,6 +60,7 @@ public static <K extends Enum<K> & MetadataKey> Metadata<K> of(Class<K> key, Map
      * Returns an instance of {@link Metadata} containing an empty set of values.
      *
      * @param key the type of metadata, must not be {@code null}
+     * @param <K> the type key type
      * @return the new metadata
      */
     public static <K extends Enum<K> & MetadataKey> Metadata<K> of(Class<K> key) {
@@ -71,6 +75,7 @@ public static <K extends Enum<K> & MetadataKey> Metadata<K> of(Class<K> key) {
      * If the current set of metadata contains already an instance of the class of {@code item}, the value is replaced
      * in the returned {@link Metadata}.
      *
+     * @param key the key, must not be {@code null}
      * @param item the metadata to be added, must not be {@code null}.
      * @return the new instance of {@link Metadata}
      */
@@ -86,11 +91,20 @@ public Metadata<T> with(T key, Object item) {
         return new Metadata<>(this.clazz, copy);
     }
 
+    /**
+     * @return the metadata
+     */
     public EnumMap<T, Object> getMetadata() {
         return metadata;
     }
 
+    /**
+     * The default metadata key.
+     */
     public enum DefaultMetadataKey implements MetadataKey {
+        /**
+         * The key.
+         */
         GENERIC_METADATA_KEY("generic");
 
         private final String name;

api/src/main/java/io/smallrye/stork/api/MetadataKey.java

@@ -1,5 +1,11 @@
 package io.smallrye.stork.api;
 
+/**
+ * Interface representing metadata key.
+ */
 public interface MetadataKey {
+    /**
+     * @return the name
+     */
     String getName();
 }

api/src/main/java/io/smallrye/stork/api/NoAcceptableServiceInstanceFoundException.java

@@ -4,10 +4,22 @@
  * Thrown by {@link LoadBalancer} when all available services are not acceptable for some, arbitrary, reason
  */
 public class NoAcceptableServiceInstanceFoundException extends NoServiceInstanceFoundException {
+
+    /**
+     * Creates a new NoAcceptableServiceInstanceFoundException.
+     *
+     * @param message the message
+     */
     public NoAcceptableServiceInstanceFoundException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new NoAcceptableServiceInstanceFoundException.
+     *
+     * @param message the message
+     * @param cause the cause
+     */
     public NoAcceptableServiceInstanceFoundException(String message, Throwable cause) {
         super(message, cause);
     }

api/src/main/java/io/smallrye/stork/api/NoServiceInstanceFoundException.java

@@ -5,10 +5,22 @@
  * or all available services are not valid to select, e.g. are determined to be faulty
  */
 public class NoServiceInstanceFoundException extends RuntimeException {
+
+    /**
+     * Creates a new NoServiceInstanceFoundException.
+     * 
+     * @param message the error message
+     */
     public NoServiceInstanceFoundException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new NoServiceInstanceFoundException.
+     *
+     * @param message the error message
+     * @param cause the cause
+     */
     public NoServiceInstanceFoundException(String message, Throwable cause) {
         super(message, cause);
     }

api/src/main/java/io/smallrye/stork/api/NoSuchServiceDefinitionException.java

@@ -5,6 +5,11 @@
  */
 public class NoSuchServiceDefinitionException extends RuntimeException {
 
+    /**
+     * Creates a new instance of NoSuchServiceDefinitionException.
+     *
+     * @param serviceName the service name
+     */
     public NoSuchServiceDefinitionException(String serviceName) {
         super("No service defined for name " + serviceName);
     }

api/src/main/java/io/smallrye/stork/api/Service.java

@@ -18,6 +18,14 @@ public class Service {
     private final ServiceDiscovery serviceDiscovery;
     private final String serviceName;
 
+    /**
+     * Creates a new Service.
+     *
+     * @param serviceName the name, must not be {@code null}, must not be blank
+     * @param loadBalancer the load balancer, can be {@code null}
+     * @param serviceDiscovery the service discovery, must not be {@code null}
+     * @param requiresStrictRecording whether strict recording must be enabled
+     */
     public Service(String serviceName, LoadBalancer loadBalancer, ServiceDiscovery serviceDiscovery,
             boolean requiresStrictRecording) {
         this.loadBalancer = loadBalancer;

api/src/main/java/io/smallrye/stork/api/ServiceInstance.java

@@ -79,7 +79,6 @@ default void recordReply() {
 
     /**
      * When {@code gatherStatistics} is enabled, reports the end of an operation using this service instance.
-     * <p>
      *
      * @param failure if the operation failed, the throwable depicting the failure, {@code null} otherwise
      */

api/src/main/java/io/smallrye/stork/api/config/LoadBalancerAttributes.java

@@ -5,6 +5,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotation used to define arrays of {@link LoadBalancerAttribute}.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface LoadBalancerAttributes {

api/src/main/java/io/smallrye/stork/api/config/ServiceDiscoveryAttributes.java

@@ -5,6 +5,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotation used to define arrays of {@link ServiceDiscoveryAttribute}.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface ServiceDiscoveryAttributes {

api/src/main/java/io/smallrye/stork/spi/CallStatisticsCollector.java

@@ -6,13 +6,31 @@
  */
 public interface CallStatisticsCollector {
 
+    /**
+     * Records the start of an operation.
+     *
+     * @param serviceInstanceId the service instance id
+     * @param measureTime whether the time must be measured
+     */
     default void recordStart(long serviceInstanceId, boolean measureTime) {
     }
 
+    /**
+     * Records the response from an operation.
+     *
+     * @param serviceInstanceId the service instance id
+     * @param timeInNanos the duration of the operation in nanoseconds
+     */
     default void recordReply(long serviceInstanceId, long timeInNanos) {
 
     }
 
+    /**
+     * Records the completion of an operation.
+     *
+     * @param serviceInstanceId the service instance id
+     * @param error the error thrown by the operation if the operation failed
+     */
     default void recordEnd(long serviceInstanceId, Throwable error) {
     }
 }

api/src/main/java/io/smallrye/stork/spi/ElementWithType.java

@@ -1,5 +1,13 @@
 package io.smallrye.stork.spi;
 
+/**
+ * A class having a {@link #type()} method such a load balancer and service discovery providers.
+ */
 public interface ElementWithType {
+    /**
+     * Gets the type.
+     * 
+     * @return the type, must not be {@code null}, must not be blank
+     */
     String type();
 }

api/src/main/java/io/smallrye/stork/spi/LoadBalancerProvider.java

@@ -3,6 +3,21 @@
 import io.smallrye.stork.api.LoadBalancer;
 import io.smallrye.stork.api.ServiceDiscovery;
 
+/**
+ * A load balancer provider allowing to create instances of load balancers.
+ * <p>
+ * Implementation should use the {@link io.smallrye.stork.api.config.LoadBalancerAttribute} to define attributes.
+ *
+ * @param <T> the configuration type (class generated from the {@link io.smallrye.stork.api.config.LoadBalancerAttribute}
+ *        annotations).
+ */
 public interface LoadBalancerProvider<T> {
+    /**
+     * Creates a load balancer instance
+     *
+     * @param config the configuration
+     * @param serviceDiscovery the service discovery used for that service
+     * @return the load balancer
+     */
     LoadBalancer createLoadBalancer(T config, ServiceDiscovery serviceDiscovery);
 }

api/src/main/java/io/smallrye/stork/spi/ServiceDiscoveryProvider.java

@@ -3,7 +3,25 @@
 import io.smallrye.stork.api.ServiceDiscovery;
 import io.smallrye.stork.api.config.ServiceConfig;
 
+/**
+ * A service discovery provider allowing to create instances of service discovery.
+ * <p>
+ * Implementation should use the {@link io.smallrye.stork.api.config.ServiceDiscoveryAttribute} to define attributes.
+ *
+ * @param <T> the configuration type (class generated from the {@link io.smallrye.stork.api.config.ServiceDiscoveryAttribute}
+ *        annotations).
+ */
 public interface ServiceDiscoveryProvider<T> {
+
+    /**
+     * Creates a new instance of {@link ServiceDiscovery}.
+     *
+     * @param config the configuration, must not be {@code null}
+     * @param serviceName the service name, must not be {@code null}, or blank.
+     * @param serviceConfig the service config, must not be {@code null}
+     * @param storkInfrastructure the stork infrastructure, must not be {@code null}
+     * @return the service discovery instance
+     */
     ServiceDiscovery createServiceDiscovery(T config, String serviceName,
             ServiceConfig serviceConfig, StorkInfrastructure storkInfrastructure);
 }