docs: builder, enum, and union comments (#467)

Author: stainless-app[bot]

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

@@ -22,6 +22,7 @@ class LithicOkHttpClient private constructor() {
         @JvmStatic fun fromEnv(): LithicClient = builder().fromEnv().build()
     }
 
+    /** A builder for [LithicOkHttpClient]. */
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()

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

@@ -22,6 +22,7 @@ class LithicOkHttpClientAsync private constructor() {
         @JvmStatic fun fromEnv(): LithicClientAsync = builder().fromEnv().build()
     }
 
+    /** A builder for [LithicOkHttpClientAsync]. */
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()

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

@@ -39,6 +39,7 @@ private constructor(
         @JvmStatic fun fromEnv(): ClientOptions = builder().fromEnv().build()
     }
 
+    /** A builder for [ClientOptions]. */
     class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null

lithic-java-core/src/main/kotlin/com/lithic/api/errors/LithicError.kt

@@ -30,6 +30,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
+    /** A builder for [LithicError]. */
     class Builder internal constructor() {
 
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()

lithic-java-core/src/main/kotlin/com/lithic/api/models/Account.kt

@@ -188,6 +188,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
+    /** A builder for [Account]. */
     class Builder internal constructor() {
 
         private var token: JsonField<String>? = null
@@ -448,6 +449,7 @@ private constructor(
             @JvmStatic fun builder() = Builder()
         }
 
+        /** A builder for [SpendLimit]. */
         class Builder internal constructor() {
 
             private var daily: JsonField<Long>? = null
@@ -543,6 +545,14 @@ private constructor(
         private val value: JsonField<String>,
     ) : Enum {
 
+        /**
+         * Returns this class instance's raw value.
+         *
+         * This is usually only useful if this instance was deserialized from data that doesn't
+         * match any known member, and you want to know that value. For example, if the SDK is on an
+         * older version than the API, then the API may respond with new members that the SDK is
+         * unaware of.
+         */
         @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField<String> = value
 
         companion object {
@@ -556,19 +566,37 @@ private constructor(
             @JvmStatic fun of(value: String) = State(JsonField.of(value))
         }
 
+        /** An enum containing [State]'s known values. */
         enum class Known {
             ACTIVE,
             PAUSED,
             CLOSED,
         }
 
+        /**
+         * An enum containing [State]'s known values, as well as an [_UNKNOWN] member.
+         *
+         * An instance of [State] can contain an unknown value in a couple of cases:
+         * - It was deserialized from data that doesn't match any known member. For example, if the
+         *   SDK is on an older version than the API, then the API may respond with new members that
+         *   the SDK is unaware of.
+         * - It was constructed with an arbitrary value using the [of] method.
+         */
         enum class Value {
             ACTIVE,
             PAUSED,
             CLOSED,
+            /** An enum member indicating that [State] was instantiated with an unknown value. */
             _UNKNOWN,
         }
 
+        /**
+         * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN]
+         * if the class was instantiated with an unknown value.
+         *
+         * Use the [known] method instead if you're certain the value is always known or if you want
+         * to throw for the unknown case.
+         */
         fun value(): Value =
             when (this) {
                 ACTIVE -> Value.ACTIVE
@@ -577,6 +605,15 @@ private constructor(
                 else -> Value._UNKNOWN
             }
 
+        /**
+         * Returns an enum member corresponding to this class instance's value.
+         *
+         * Use the [value] method instead if you're uncertain the value is always known and don't
+         * want to throw for the unknown case.
+         *
+         * @throws LithicInvalidDataException if this class instance's value is a not a known
+         *   member.
+         */
         fun known(): Known =
             when (this) {
                 ACTIVE -> Known.ACTIVE
@@ -682,6 +719,7 @@ private constructor(
             @JvmStatic fun builder() = Builder()
         }
 
+        /** A builder for [AccountHolder]. */
         class Builder internal constructor() {
 
             private var token: JsonField<String>? = null
@@ -887,6 +925,7 @@ private constructor(
             @JvmStatic fun builder() = Builder()
         }
 
+        /** A builder for [VerificationAddress]. */
         class Builder internal constructor() {
 
             private var address1: JsonField<String>? = null

lithic-java-core/src/main/kotlin/com/lithic/api/models/AccountFinancialAccountType.kt

@@ -14,6 +14,13 @@ private constructor(
     private val value: JsonField<String>,
 ) : Enum {
 
+    /**
+     * Returns this class instance's raw value.
+     *
+     * This is usually only useful if this instance was deserialized from data that doesn't match
+     * any known member, and you want to know that value. For example, if the SDK is on an older
+     * version than the API, then the API may respond with new members that the SDK is unaware of.
+     */
     @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField<String> = value
 
     companion object {
@@ -25,24 +32,55 @@ private constructor(
         @JvmStatic fun of(value: String) = AccountFinancialAccountType(JsonField.of(value))
     }
 
+    /** An enum containing [AccountFinancialAccountType]'s known values. */
     enum class Known {
         ISSUING,
         OPERATING,
     }
 
+    /**
+     * An enum containing [AccountFinancialAccountType]'s known values, as well as an [_UNKNOWN]
+     * member.
+     *
+     * An instance of [AccountFinancialAccountType] can contain an unknown value in a couple of
+     * cases:
+     * - It was deserialized from data that doesn't match any known member. For example, if the SDK
+     *   is on an older version than the API, then the API may respond with new members that the SDK
+     *   is unaware of.
+     * - It was constructed with an arbitrary value using the [of] method.
+     */
     enum class Value {
         ISSUING,
         OPERATING,
+        /**
+         * An enum member indicating that [AccountFinancialAccountType] was instantiated with an
+         * unknown value.
+         */
         _UNKNOWN,
     }
 
+    /**
+     * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN] if
+     * the class was instantiated with an unknown value.
+     *
+     * Use the [known] method instead if you're certain the value is always known or if you want to
+     * throw for the unknown case.
+     */
     fun value(): Value =
         when (this) {
             ISSUING -> Value.ISSUING
             OPERATING -> Value.OPERATING
             else -> Value._UNKNOWN
         }
 
+    /**
+     * Returns an enum member corresponding to this class instance's value.
+     *
+     * Use the [value] method instead if you're uncertain the value is always known and don't want
+     * to throw for the unknown case.
+     *
+     * @throws LithicInvalidDataException if this class instance's value is a not a known member.
+     */
     fun known(): Known =
         when (this) {
             ISSUING -> Known.ISSUING