Minor: improve docs for CordaRPCClientConfiguration and deprecate a field that is no longer used.

client/rpc/src/main/kotlin/net/corda/client/rpc/CordaRPCClient.kt

@@ -29,7 +29,8 @@ class CordaRPCConnection internal constructor(connection: RPCConnection<CordaRPC
 open class CordaRPCClientConfiguration @JvmOverloads constructor(
 
         /**
-         * Maximum retry interval.
+         * The maximum retry interval for re-connections. The client will retry connections if the host is lost with
+         * ever increasing spacing until the max is reached. The default is 3 minutes.
          */
         open val connectionMaxRetryInterval: Duration = 3.minutes,
 
@@ -48,55 +49,56 @@ open class CordaRPCClientConfiguration @JvmOverloads constructor(
         open val minimumServerProtocolVersion: Int = 4,
 
         /**
-         * If set to true the client will track RPC call sites. If an error occurs subsequently during the RPC or in a
+         * If set to true the client will track RPC call sites (default is false). If an error occurs subsequently
-         * returned Observable stream the stack trace of the originating RPC will be shown as well. Note that
+         * during the RPC or in a returned Observable stream the stack trace of the originating RPC will be shown as
-         * constructing call stacks is a moderately expensive operation.
+         * well. Note that constructing call stacks is a moderately expensive operation.
          */
         open val trackRpcCallSites: Boolean = java.lang.Boolean.getBoolean("net.corda.client.rpc.trackRpcCallSites"),
 
         /**
          * The interval of unused observable reaping. Leaked Observables (unused ones) are detected using weak references
          * and are cleaned up in batches in this interval. If set too large it will waste server side resources for this
-         * duration. If set too low it wastes client side cycles.
+         * duration. If set too low it wastes client side cycles. The default is to check once per second.
          */
         open val reapInterval: Duration = 1.seconds,
 
         /**
-         * The number of threads to use for observations (for executing [Observable.onNext]).
+         * The number of threads to use for observations for executing [Observable.onNext]. This only has any effect
+         * if [observableExecutor] is null (which is the default). The default is 4.
          */
         open val observationExecutorPoolSize: Int = 4,
 
         /**
-         * Determines the concurrency level of the Observable Cache. This is exposed because it implicitly determines
+         * This property is no longer used and has no effect.
-         * the limit on the number of leaked observables reaped because of garbage collection per reaping.
+         * @suppress
-         * See the implementation of [com.google.common.cache.LocalCache] for details.
          */
+        @Deprecated("This field is no longer used and has no effect.")
         open val cacheConcurrencyLevel: Int = 1,
 
         /**
-         * The retry interval of Artemis connections in milliseconds.
+         * The base retry interval for reconnection attempts. The default is 5 seconds.
          */
         open val connectionRetryInterval: Duration = 5.seconds,
 
         /**
-         * The retry interval multiplier for exponential backoff.
+         * The retry interval multiplier for exponential backoff. The default is 1.5
          */
         open val connectionRetryIntervalMultiplier: Double = 1.5,
 
         /**
-         * Maximum reconnect attempts on failover>
+         * Maximum reconnect attempts on failover or disconnection. The default is -1 which means unlimited.
          */
         open val maxReconnectAttempts: Int = unlimitedReconnectAttempts,
 
         /**
-         * Maximum file size, in bytes.
+         * Maximum size of RPC responses, in bytes. Default is 10mb.
          */
         open val maxFileSize: Int = 10485760,
         // 10 MiB maximum allowed file size for attachments, including message headers.
         // TODO: acquire this value from Network Map when supported.
 
         /**
-         * The cache expiry of a deduplication watermark per client.
+         * The cache expiry of a deduplication watermark per client. Default is 1 day.
          */
         open val deduplicationCacheExpiry: Duration = 1.days
 
@@ -106,6 +108,7 @@ open class CordaRPCClientConfiguration @JvmOverloads constructor(
 
         private const val unlimitedReconnectAttempts = -1
 
+        /** Provides an instance of this class with the parameters set to our recommended defaults. */
         @JvmField
         val DEFAULT: CordaRPCClientConfiguration = CordaRPCClientConfiguration()
 
@@ -113,7 +116,10 @@ open class CordaRPCClientConfiguration @JvmOverloads constructor(
 
     /**
      * Create a new copy of a configuration object with zero or more parameters modified.
+     *
+     * @suppress
      */
+    @Suppress("DEPRECATION")
     @JvmOverloads
     fun copy(
             connectionMaxRetryInterval: Duration = this.connectionMaxRetryInterval,
@@ -178,6 +184,7 @@ open class CordaRPCClientConfiguration @JvmOverloads constructor(
         return result
     }
 
+    @Suppress("DEPRECATION")
     override fun toString(): String {
         return "CordaRPCClientConfiguration(" +
                 "connectionMaxRetryInterval=$connectionMaxRetryInterval, " +
@@ -189,7 +196,8 @@ open class CordaRPCClientConfiguration @JvmOverloads constructor(
                 "deduplicationCacheExpiry=$deduplicationCacheExpiry)"
     }
 
-    // Left is for backwards compatibility with version 3.1
+    // Left in for backwards compatibility with version 3.1
+    @Deprecated("Binary compatibility stub")
     operator fun component1() = connectionMaxRetryInterval
 
 }