docs: add client documentation (#464)

Author: stainless-app[bot]

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClient.kt

@@ -34,6 +34,20 @@ import com.lithic.api.services.blocking.TransactionService
 import com.lithic.api.services.blocking.TransferService
 import com.lithic.api.services.blocking.WebhookService
 
+/**
+ * A client for interacting with the Lithic REST API synchronously. You can also switch to
+ * asynchronous execution via the [async] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface LithicClient {
 
     fun async(): LithicClientAsync

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsync.kt

@@ -35,6 +35,20 @@ import com.lithic.api.services.async.TransferServiceAsync
 import com.lithic.api.services.async.WebhookServiceAsync
 import java.util.concurrent.CompletableFuture
 
+/**
+ * A client for interacting with the Lithic REST API asynchronously. You can also switch to
+ * synchronous execution via the [sync] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface LithicClientAsync {
 
     fun sync(): LithicClient