Merge pull request #49 from launchdarkly/eb/javadoc-fixes

misc javadoc fixes

Author: eli-darkly

src/main/java/com/launchdarkly/client/FeatureStore.java

@@ -19,6 +19,7 @@ public interface FeatureStore extends Closeable {
    * null if the key is not associated or the associated object has
    * been deleted.
    *
+   * @param <T> class of the object that will be returned
    * @param kind the kind of object to get
    * @param key the key whose associated object is to be returned
    * @return the object to which the specified key is mapped, or
@@ -30,6 +31,7 @@ public interface FeatureStore extends Closeable {
   /**
    * Returns a {@link java.util.Map} of all associated objects of a given kind.
    *
+   * @param <T> class of the objects that will be returned in the map
    * @param kind the kind of objects to get
    * @return a map of all associated object.
    */
@@ -49,6 +51,7 @@ public interface FeatureStore extends Closeable {
    * Deletes the object associated with the specified key, if it exists and its version
    * is less than or equal to the specified version.
    *
+   * @param <T> class of the object to be deleted
    * @param kind the kind of object to delete
    * @param key the key of the object to be deleted
    * @param version the version for the delete operation
@@ -59,8 +62,9 @@ public interface FeatureStore extends Closeable {
    * Update or insert the object associated with the specified key, if its version
    * is less than or equal to the version specified in the argument object.
    *
+   * @param <T> class of the object to be updated
    * @param kind the kind of object to update
-   * @param item
+   * @param item the object to update or insert
    */
   <T extends VersionedData> void upsert(VersionedDataKind<T> kind, T item);
 

src/main/java/com/launchdarkly/client/InMemoryFeatureStore.java

@@ -9,8 +9,8 @@
 import java.util.concurrent.locks.ReentrantReadWriteLock;
 
 /**
- * A thread-safe, versioned store for {@link FeatureFlag} objects based on a
- * {@link HashMap}
+ * A thread-safe, versioned store for {@link FeatureFlag} objects and related data based on a
+ * {@link HashMap}.
  */
 public class InMemoryFeatureStore implements FeatureStore {
   private static final Logger logger = LoggerFactory.getLogger(InMemoryFeatureStore.class);
@@ -19,17 +19,6 @@ public class InMemoryFeatureStore implements FeatureStore {
   private final Map<VersionedDataKind<?>, Map<String, VersionedData>> allData = new HashMap<>();
   private volatile boolean initialized = false;
 
-
-  /**
-   * Returns the {@link FeatureFlag} to which the specified key is mapped, or
-   * null if the key is not associated or the associated {@link FeatureFlag} has
-   * been deleted.
-   *
-   * @param key the key whose associated {@link FeatureFlag} is to be returned
-   * @return the {@link FeatureFlag} to which the specified key is mapped, or
-   * null if the key is not associated or the associated {@link FeatureFlag} has
-   * been deleted.
-   */
   @Override
   public <T extends VersionedData> T get(VersionedDataKind<T> kind, String key) {
     try {
@@ -61,11 +50,6 @@ public <T extends VersionedData> T get(VersionedDataKind<T> kind, String key) {
     }
   }
 
-  /**
-   * Returns a {@link java.util.Map} of all associated features.
-   *
-   * @return a map of all associated features.
-   */
   @Override
   public <T extends VersionedData> Map<String, T> all(VersionedDataKind<T> kind) {
     try {
@@ -85,13 +69,6 @@ public <T extends VersionedData> Map<String, T> all(VersionedDataKind<T> kind) {
     }
   }
 
-
-  /**
-   * Initializes (or re-initializes) the store with the specified set of features. Any existing entries
-   * will be removed.
-   *
-   * @param features the features to set the store
-   */
   @SuppressWarnings("unchecked")
   @Override
   public void init(Map<VersionedDataKind<?>, Map<String, ? extends VersionedData>> allData) {
@@ -107,13 +84,6 @@ public void init(Map<VersionedDataKind<?>, Map<String, ? extends VersionedData>>
     }
   }
 
-  /**
-   * Deletes the feature associated with the specified key, if it exists and its version
-   * is less than or equal to the specified version.
-   *
-   * @param key     the key of the feature to be deleted
-   * @param version the version for the delete operation
-   */
   @Override
   public <T extends VersionedData> void delete(VersionedDataKind<T> kind, String key, int version) {
     try {
@@ -132,13 +102,6 @@ public <T extends VersionedData> void delete(VersionedDataKind<T> kind, String k
     }
   }
 
-  /**
-   * Update or insert the feature associated with the specified key, if its version
-   * is less than or equal to the version specified in the argument feature.
-   *
-   * @param key
-   * @param feature
-   */
   @Override
   public <T extends VersionedData> void upsert(VersionedDataKind<T> kind, T item) {
     try {
@@ -158,11 +121,6 @@ public <T extends VersionedData> void upsert(VersionedDataKind<T> kind, T item)
     }
   }
 
-  /**
-   * Returns true if this store has been initialized
-   *
-   * @return true if this store has been initialized
-   */
   @Override
   public boolean initialized() {
     return initialized;
@@ -171,7 +129,7 @@ public boolean initialized() {
   /**
    * Does nothing; this class does not have any resources to release
    *
-   * @throws IOException
+   * @throws IOException will never happen
    */
   @Override
   public void close() throws IOException {

src/main/java/com/launchdarkly/client/LDClient.java

@@ -384,7 +384,7 @@ private JsonElement evaluate(String featureKey, LDUser user, JsonElement default
    * Closes the LaunchDarkly client event processing thread. This should only
    * be called on application shutdown.
    *
-   * @throws IOException
+   * @throws IOException if an exception is thrown by one of the underlying network services
    */
   @Override
   public void close() throws IOException {

src/main/java/com/launchdarkly/client/LDConfig.java

@@ -136,7 +136,6 @@ Request.Builder getRequestBuilder(String sdkKey) {
   /**
    * A <a href="http://en.wikipedia.org/wiki/Builder_pattern">builder</a> that helps construct {@link com.launchdarkly.client.LDConfig} objects. Builder
    * calls can be chained, enabling the following pattern:
-   * <p>
    * <pre>
    * LDConfig config = new LDConfig.Builder()
    *      .connectTimeoutMillis(3)
@@ -227,7 +226,6 @@ public Builder stream(boolean stream) {
     /**
      * Set the connection timeout in seconds for the configuration. This is the time allowed for the underlying HTTP client to connect
      * to the LaunchDarkly server. The default is 2 seconds.
-     * <p>
      * <p>Both this method and {@link #connectTimeoutMillis(int) connectTimeoutMillis} affect the same property internally.</p>
      *
      * @param connectTimeout the connection timeout in seconds
@@ -241,7 +239,6 @@ public Builder connectTimeout(int connectTimeout) {
     /**
      * Set the socket timeout in seconds for the configuration. This is the number of seconds between successive packets that the
      * client will tolerate before flagging an error. The default is 10 seconds.
-     * <p>
      * <p>Both this method and {@link #socketTimeoutMillis(int) socketTimeoutMillis} affect the same property internally.</p>
      *
      * @param socketTimeout the socket timeout in seconds
@@ -255,7 +252,6 @@ public Builder socketTimeout(int socketTimeout) {
     /**
      * Set the connection timeout in milliseconds for the configuration. This is the time allowed for the underlying HTTP client to connect
      * to the LaunchDarkly server. The default is 2000 ms.
-     * <p>
      * <p>Both this method and {@link #connectTimeout(int) connectTimeoutMillis} affect the same property internally.</p>
      *
      * @param connectTimeoutMillis the connection timeout in milliseconds
@@ -269,7 +265,6 @@ public Builder connectTimeoutMillis(int connectTimeoutMillis) {
     /**
      * Set the socket timeout in milliseconds for the configuration. This is the number of milliseconds between successive packets that the
      * client will tolerate before flagging an error. The default is 10,000 milliseconds.
-     * <p>
      * <p>Both this method and {@link #socketTimeout(int) socketTimeoutMillis} affect the same property internally.</p>
      *
      * @param socketTimeoutMillis the socket timeout in milliseconds
@@ -312,7 +307,7 @@ public Builder capacity(int capacity) {
      * a proxy will not be used, and {@link LDClient} will connect to LaunchDarkly directly.
      * </p>
      *
-     * @param host
+     * @param host the proxy hostname
      * @return the builder
      */
     public Builder proxyHost(String host) {
@@ -323,7 +318,7 @@ public Builder proxyHost(String host) {
     /**
      * Set the port to use for an HTTP proxy for making connections to LaunchDarkly. This is required for proxied HTTP connections.
      *
-     * @param port
+     * @param port the proxy port
      * @return the builder
      */
     public Builder proxyPort(int port) {
@@ -335,7 +330,7 @@ public Builder proxyPort(int port) {
      * Sets the username for the optional HTTP proxy. Only used when {@link LDConfig.Builder#proxyPassword(String)}
      * is also called.
      *
-     * @param username
+     * @param username the proxy username
      * @return the builder
      */
     public Builder proxyUsername(String username) {
@@ -347,7 +342,7 @@ public Builder proxyUsername(String username) {
      * Sets the password for the optional HTTP proxy. Only used when {@link LDConfig.Builder#proxyUsername(String)}
      * is also called.
      *
-     * @param password
+     * @param password the proxy password
      * @return the builder
      */
     public Builder proxyPassword(String password) {
@@ -358,7 +353,7 @@ public Builder proxyPassword(String password) {
     /**
      * Deprecated. Only HTTP proxies are currently supported.
      *
-     * @param unused
+     * @param unused the proxy scheme
      * @return the builder
      */
     @Deprecated
@@ -367,10 +362,10 @@ public Builder proxyScheme(String unused) {
     }
 
     /**
-     * Set whether this client should subscribe to the streaming API, or whether the LaunchDarkly daemon is in use
-     * instead
+     * Set whether this client should use the <a href="https://docs.launchdarkly.com/docs/the-relay-proxy">LaunchDarkly
+     * relay</a> in daemon mode, versus subscribing to the streaming or polling API.
      *
-     * @param useLdd
+     * @param useLdd true to use the relay in daemon mode; false to use streaming or polling 
      * @return the builder
      */
     public Builder useLdd(boolean useLdd) {
@@ -381,7 +376,7 @@ public Builder useLdd(boolean useLdd) {
     /**
      * Set whether this client is offline.
      *
-     * @param offline when set to true no calls to LaunchDarkly will be made.
+     * @param offline when set to true no calls to LaunchDarkly will be made
      * @return the builder
      */
     public Builder offline(boolean offline) {
@@ -390,10 +385,10 @@ public Builder offline(boolean offline) {
     }
 
     /**
-     * Set whether or not user attributes (other than the key) should be sent back to LaunchDarkly. If this is true, all
+     * Set whether or not user attributes (other than the key) should be hidden from LaunchDarkly. If this is true, all
      * user attribute values will be private, not just the attributes specified in {@link #privateAttributeNames(String...)}. By default,
      * this is false.
-     * @param allPrivate
+     * @param allPrivate true if all user attributes should be private
      * @return the builder
      */
     public Builder allAttributesPrivate(boolean allPrivate) {
@@ -406,7 +401,7 @@ public Builder allAttributesPrivate(boolean allPrivate) {
      * events. This differs from {@link offline} in that it only affects sending
      * analytics events, not streaming or polling for events from the server.
      *
-     * @param sendEvents when set to false, no events will be sent to LaunchDarkly.
+     * @param sendEvents when set to false, no events will be sent to LaunchDarkly
      * @return the builder
      */
     public Builder sendEvents(boolean sendEvents) {
@@ -418,7 +413,7 @@ public Builder sendEvents(boolean sendEvents) {
      * Set the polling interval (when streaming is disabled). Values less than the default of
      * 30000 will be set to the default.
      *
-     * @param pollingIntervalMillis rule update polling interval in milliseconds.
+     * @param pollingIntervalMillis rule update polling interval in milliseconds
      * @return the builder
      */
     public Builder pollingIntervalMillis(long pollingIntervalMillis) {
@@ -443,7 +438,6 @@ public Builder startWaitMillis(long startWaitMillis) {
      * Enable event sampling. When set to the default of zero, sampling is disabled and all events
      * are sent back to LaunchDarkly. When set to greater than zero, there is a 1 in
      * <code>samplingInterval</code> chance events will be will be sent.
-     * <p>
      * <p>Example: if you want 5% sampling rate, set <code>samplingInterval</code> to 20.
      *
      * @param samplingInterval the sampling interval.

src/main/java/com/launchdarkly/client/LDCountryCode.java

@@ -2257,7 +2257,7 @@ public Assignment getAssignment()
    * </p>
    *
    * <table border="1" style="border-collapse: collapse;" cellpadding="5" summary="">
-   * <tr bgcolor="#FF8C00">
+   * <tr style="background-color: #ff8c00;">
    *   <th>CountryCode</th>
    *   <th>Locale</th>
    * </tr>

src/main/java/com/launchdarkly/client/LDUser.java

@@ -290,7 +290,6 @@ public LDUser read(JsonReader in) throws IOException {
   /**
    * A <a href="http://en.wikipedia.org/wiki/Builder_pattern">builder</a> that helps construct {@link LDUser} objects. Builder
    * calls can be chained, enabling the following pattern:
-   * <p>
    * <pre>
    * LDUser user = new LDUser.Builder("key")
    *      .country("US")

src/main/java/com/launchdarkly/client/RedisFeatureStore.java

@@ -339,11 +339,6 @@ public <T extends VersionedData> void upsert(VersionedDataKind<T> kind, T item)
     }
   }
 
-  /**
-   * Returns true if this store has been initialized
-   *
-   * @return true if this store has been initialized
-   */
   @Override
   public boolean initialized() {
     // The LoadingCache takes care of both coalescing multiple simultaneous requests and memoizing
@@ -355,7 +350,7 @@ public boolean initialized() {
   /**
    * Releases all resources associated with the store. The store must no longer be used once closed.
    *
-   * @throws IOException
+   * @throws IOException if an underlying service threw an exception
    */
   public void close() throws IOException {
     logger.info("Closing LaunchDarkly RedisFeatureStore");

src/main/java/com/launchdarkly/client/RedisFeatureStoreBuilder.java

@@ -52,7 +52,7 @@ public RedisFeatureStoreBuilder(URI uri, long cacheTimeSecs) {
      * @param host the hostname to connect to
      * @param port the port to connect to
      * @param cacheTimeSecs the cache time in seconds. See {@link RedisFeatureStoreBuilder#cacheTime(long, TimeUnit)} for more information.
-     * @throws URISyntaxException
+     * @throws URISyntaxException if the URI is not valid
      */
     public RedisFeatureStoreBuilder(String scheme, String host, int port, long cacheTimeSecs) throws URISyntaxException {
         this.uri = new URI(scheme, null, host, port, null, null, null);
@@ -110,7 +110,7 @@ public RedisFeatureStoreBuilder asyncRefresh(boolean enabled) {
     /**
      * Optionally configures the namespace prefix for all keys stored in Redis.
      *
-     * @param prefix
+     * @param prefix the namespace prefix
      * @return the builder
      */
     public RedisFeatureStoreBuilder prefix(String prefix) {

src/main/java/com/launchdarkly/client/TestFeatureStore.java

@@ -44,14 +44,15 @@ public void setBooleanValue(String key, Boolean value) {
    * Turns a feature, identified by key, to evaluate to true for every user. If the feature rules already exist in the store then it will override it to be true for every {@link LDUser}.
    * If the feature rule is not currently in the store, it will create one that is true for every {@link LDUser}.
    *
-   * @param key the key of the feature flag to evaluate to true.
+   * @param key the key of the feature flag to evaluate to true
    */
   public void setFeatureTrue(String key) {
     setBooleanValue(key, true);
   }
 
   /**
    * @deprecated use {@link #setFeatureTrue(String key)}
+   * @param key the feature key
    */
   @Deprecated
   public void turnFeatureOn(String key) {
@@ -62,14 +63,15 @@ public void turnFeatureOn(String key) {
    * Turns a feature, identified by key, to evaluate to false for every user. If the feature rules already exist in the store then it will override it to be false for every {@link LDUser}.
    * If the feature rule is not currently in the store, it will create one that is false for every {@link LDUser}.
    *
-   * @param key the key of the feature flag to evaluate to false.
+   * @param key the key of the feature flag to evaluate to false
    */
   public void setFeatureFalse(String key) {
     setBooleanValue(key, false);
   }
 
   /**
    * @deprecated use {@link #setFeatureFalse(String key)}
+   * @param key the feature key
    */
   @Deprecated
   public void turnFeatureOff(String key) {

src/main/java/com/launchdarkly/client/UpdateProcessor.java

@@ -14,7 +14,7 @@ public interface UpdateProcessor extends Closeable {
 
   /**
    * Returns true once the client has been initialized and will never return false again.
-   * @return
+   * @return true if the client has been initialized
    */
   boolean initialized();