Skip to content

Commit ceb45ee

Browse files
stainless-app[bot]stainless-app[bot]
committed
docs: more code comments
1 parent c6044f3 commit ceb45ee

171 files changed

Lines changed: 637 additions & 4 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -377,7 +377,7 @@ If the SDK threw an exception, but you're _certain_ the version is compatible, t
377377

378378
### Retries
379379

380-
The SDK automatically retries 2 times by default, with a short exponential backoff.
380+
The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
381381

382382
Only the following error types are retried:
383383

@@ -387,7 +387,7 @@ Only the following error types are retried:
387387
- 429 Rate Limit
388388
- 5xx Internal
389389

390-
The API may also explicitly instruct the SDK to retry or not retry a response.
390+
The API may also explicitly instruct the SDK to retry or not retry a request.
391391

392392
To set a custom number of retries, configure the client using the `maxRetries` method:
393393

‎lithic-java-client-okhttp/src/main/kotlin/com/lithic/api/client/okhttp/LithicOkHttpClient.kt‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ import com.lithic.api.client.LithicClient
77
import com.lithic.api.client.LithicClientImpl
88
import com.lithic.api.core.ClientOptions
99
import com.lithic.api.core.Timeout
10+
import com.lithic.api.core.http.AsyncStreamResponse
1011
import com.lithic.api.core.http.Headers
12+
import com.lithic.api.core.http.HttpClient
1113
import com.lithic.api.core.http.QueryParams
1214
import com.lithic.api.core.jsonMapper
1315
import java.net.Proxy
@@ -20,13 +22,22 @@ import javax.net.ssl.SSLSocketFactory
2022
import javax.net.ssl.X509TrustManager
2123
import kotlin.jvm.optionals.getOrNull
2224

25+
/**
26+
* A class that allows building an instance of [LithicClient] with [OkHttpClient] as the underlying
27+
* [HttpClient].
28+
*/
2329
class LithicOkHttpClient private constructor() {
2430

2531
companion object {
2632

27-
/** Returns a mutable builder for constructing an instance of [LithicOkHttpClient]. */
33+
/** Returns a mutable builder for constructing an instance of [LithicClient]. */
2834
@JvmStatic fun builder() = Builder()
2935

36+
/**
37+
* Returns a client configured using system properties and environment variables.
38+
*
39+
* @see ClientOptions.Builder.fromEnv
40+
*/
3041
@JvmStatic fun fromEnv(): LithicClient = builder().fromEnv().build()
3142
}
3243

@@ -103,25 +114,64 @@ class LithicOkHttpClient private constructor() {
103114
clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
104115
}
105116

117+
/**
118+
* The Jackson JSON mapper to use for serializing and deserializing JSON.
119+
*
120+
* Defaults to [com.lithic.api.core.jsonMapper]. The default is usually sufficient and
121+
* rarely needs to be overridden.
122+
*/
106123
fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
107124

125+
/**
126+
* The executor to use for running [AsyncStreamResponse.Handler] callbacks.
127+
*
128+
* Defaults to a dedicated cached thread pool.
129+
*/
108130
fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {
109131
clientOptions.streamHandlerExecutor(streamHandlerExecutor)
110132
}
111133

134+
/**
135+
* The clock to use for operations that require timing, like retries.
136+
*
137+
* This is primarily useful for using a fake clock in tests.
138+
*
139+
* Defaults to [Clock.systemUTC].
140+
*/
112141
fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
113142

143+
/**
144+
* The base URL to use for every request.
145+
*
146+
* Defaults to the production environment: `https://api.lithic.com`.
147+
*
148+
* The following other environments, with dedicated builder methods, are available:
149+
* - sandbox: `https://sandbox.lithic.com`
150+
*/
114151
fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
115152

116153
/** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
117154
fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
118155

156+
/** Sets [baseUrl] to `https://sandbox.lithic.com`. */
119157
fun sandbox() = apply { clientOptions.sandbox() }
120158

159+
/**
160+
* Whether to call `validate` on every response before returning it.
161+
*
162+
* Defaults to false, which means the shape of the response will not be validated upfront.
163+
* Instead, validation will only occur for the parts of the response that are accessed.
164+
*/
121165
fun responseValidation(responseValidation: Boolean) = apply {
122166
clientOptions.responseValidation(responseValidation)
123167
}
124168

169+
/**
170+
* Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
171+
* retries.
172+
*
173+
* Defaults to [Timeout.default].
174+
*/
125175
fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
126176

127177
/**
@@ -133,6 +183,21 @@ class LithicOkHttpClient private constructor() {
133183
*/
134184
fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
135185

186+
/**
187+
* The maximum number of times to retry failed requests, with a short exponential backoff
188+
* between requests.
189+
*
190+
* Only the following error types are retried:
191+
* - Connection errors (for example, due to a network connectivity problem)
192+
* - 408 Request Timeout
193+
* - 409 Conflict
194+
* - 429 Rate Limit
195+
* - 5xx Internal
196+
*
197+
* The API may also explicitly instruct the SDK to retry or not retry a request.
198+
*
199+
* Defaults to 2.
200+
*/
136201
fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
137202

138203
fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -225,6 +290,11 @@ class LithicOkHttpClient private constructor() {
225290
clientOptions.removeAllQueryParams(keys)
226291
}
227292

293+
/**
294+
* Updates configuration using system properties and environment variables.
295+
*
296+
* @see ClientOptions.Builder.fromEnv
297+
*/
228298
fun fromEnv() = apply { clientOptions.fromEnv() }
229299

230300
/**

‎lithic-java-client-okhttp/src/main/kotlin/com/lithic/api/client/okhttp/LithicOkHttpClientAsync.kt‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ import com.lithic.api.client.LithicClientAsync
77
import com.lithic.api.client.LithicClientAsyncImpl
88
import com.lithic.api.core.ClientOptions
99
import com.lithic.api.core.Timeout
10+
import com.lithic.api.core.http.AsyncStreamResponse
1011
import com.lithic.api.core.http.Headers
12+
import com.lithic.api.core.http.HttpClient
1113
import com.lithic.api.core.http.QueryParams
1214
import com.lithic.api.core.jsonMapper
1315
import java.net.Proxy
@@ -20,13 +22,22 @@ import javax.net.ssl.SSLSocketFactory
2022
import javax.net.ssl.X509TrustManager
2123
import kotlin.jvm.optionals.getOrNull
2224

25+
/**
26+
* A class that allows building an instance of [LithicClientAsync] with [OkHttpClient] as the
27+
* underlying [HttpClient].
28+
*/
2329
class LithicOkHttpClientAsync private constructor() {
2430

2531
companion object {
2632

27-
/** Returns a mutable builder for constructing an instance of [LithicOkHttpClientAsync]. */
33+
/** Returns a mutable builder for constructing an instance of [LithicClientAsync]. */
2834
@JvmStatic fun builder() = Builder()
2935

36+
/**
37+
* Returns a client configured using system properties and environment variables.
38+
*
39+
* @see ClientOptions.Builder.fromEnv
40+
*/
3041
@JvmStatic fun fromEnv(): LithicClientAsync = builder().fromEnv().build()
3142
}
3243

@@ -103,25 +114,64 @@ class LithicOkHttpClientAsync private constructor() {
103114
clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
104115
}
105116

117+
/**
118+
* The Jackson JSON mapper to use for serializing and deserializing JSON.
119+
*
120+
* Defaults to [com.lithic.api.core.jsonMapper]. The default is usually sufficient and
121+
* rarely needs to be overridden.
122+
*/
106123
fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
107124

125+
/**
126+
* The executor to use for running [AsyncStreamResponse.Handler] callbacks.
127+
*
128+
* Defaults to a dedicated cached thread pool.
129+
*/
108130
fun streamHandlerExecutor(streamHandlerExecutor: Executor) = apply {
109131
clientOptions.streamHandlerExecutor(streamHandlerExecutor)
110132
}
111133

134+
/**
135+
* The clock to use for operations that require timing, like retries.
136+
*
137+
* This is primarily useful for using a fake clock in tests.
138+
*
139+
* Defaults to [Clock.systemUTC].
140+
*/
112141
fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
113142

143+
/**
144+
* The base URL to use for every request.
145+
*
146+
* Defaults to the production environment: `https://api.lithic.com`.
147+
*
148+
* The following other environments, with dedicated builder methods, are available:
149+
* - sandbox: `https://sandbox.lithic.com`
150+
*/
114151
fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
115152

116153
/** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
117154
fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
118155

156+
/** Sets [baseUrl] to `https://sandbox.lithic.com`. */
119157
fun sandbox() = apply { clientOptions.sandbox() }
120158

159+
/**
160+
* Whether to call `validate` on every response before returning it.
161+
*
162+
* Defaults to false, which means the shape of the response will not be validated upfront.
163+
* Instead, validation will only occur for the parts of the response that are accessed.
164+
*/
121165
fun responseValidation(responseValidation: Boolean) = apply {
122166
clientOptions.responseValidation(responseValidation)
123167
}
124168

169+
/**
170+
* Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
171+
* retries.
172+
*
173+
* Defaults to [Timeout.default].
174+
*/
125175
fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
126176

127177
/**
@@ -133,6 +183,21 @@ class LithicOkHttpClientAsync private constructor() {
133183
*/
134184
fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
135185

186+
/**
187+
* The maximum number of times to retry failed requests, with a short exponential backoff
188+
* between requests.
189+
*
190+
* Only the following error types are retried:
191+
* - Connection errors (for example, due to a network connectivity problem)
192+
* - 408 Request Timeout
193+
* - 409 Conflict
194+
* - 429 Rate Limit
195+
* - 5xx Internal
196+
*
197+
* The API may also explicitly instruct the SDK to retry or not retry a request.
198+
*
199+
* Defaults to 2.
200+
*/
136201
fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
137202

138203
fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -225,6 +290,11 @@ class LithicOkHttpClientAsync private constructor() {
225290
clientOptions.removeAllQueryParams(keys)
226291
}
227292

293+
/**
294+
* Updates configuration using system properties and environment variables.
295+
*
296+
* @see ClientOptions.Builder.fromEnv
297+
*/
228298
fun fromEnv() = apply { clientOptions.fromEnv() }
229299

230300
/**

0 commit comments

Comments
 (0)