docs: add build method comments (#347)

Author: stainless-app[bot]

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClient.kt

@@ -156,6 +156,11 @@ class OrbOkHttpClient private constructor() {
 
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
+        /**
+         * Returns an immutable instance of [OrbClient].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): OrbClient =
             OrbClientImpl(
                 clientOptions

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClientAsync.kt

@@ -156,6 +156,11 @@ class OrbOkHttpClientAsync private constructor() {
 
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
+        /**
+         * Returns an immutable instance of [OrbClientAsync].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): OrbClientAsync =
             OrbClientAsyncImpl(
                 clientOptions

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

@@ -189,6 +189,19 @@ private constructor(
             System.getenv("ORB_WEBHOOK_SECRET")?.let { webhookSecret(it) }
         }
 
+        /**
+         * Returns an immutable instance of [ClientOptions].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .httpClient()
+         * .apiKey()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): ClientOptions {
             val httpClient = checkRequired("httpClient", httpClient)
             val apiKey = checkRequired("apiKey", apiKey)

orb-java-core/src/main/kotlin/com/withorb/api/core/Timeout.kt

@@ -132,6 +132,11 @@ private constructor(
         /** Alias for calling [Builder.request] with `request.orElse(null)`. */
         fun request(request: Optional<Duration>) = request(request.getOrNull())
 
+        /**
+         * Returns an immutable instance of [Timeout].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): Timeout = Timeout(connect, read, write, request)
     }
 

orb-java-core/src/main/kotlin/com/withorb/api/errors/OrbError.kt

@@ -60,6 +60,11 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [OrbError].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): OrbError = OrbError(additionalProperties.toImmutable())
     }
 

orb-java-core/src/main/kotlin/com/withorb/api/models/Alert.kt

@@ -464,6 +464,27 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [Alert].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .id()
+         * .createdAt()
+         * .currency()
+         * .customer()
+         * .enabled()
+         * .metric()
+         * .plan()
+         * .subscription()
+         * .thresholds()
+         * .type()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): Alert =
             Alert(
                 checkRequired("id", id),
@@ -620,6 +641,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Customer].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .id()
+             * .externalCustomerId()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Customer =
                 Customer(
                     checkRequired("id", id),
@@ -741,6 +775,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Metric].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .id()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Metric =
                 Metric(checkRequired("id", id), additionalProperties.toImmutable())
         }
@@ -980,6 +1026,21 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Plan].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .id()
+             * .externalPlanId()
+             * .name()
+             * .planVersion()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Plan =
                 Plan(
                     checkRequired("id", id),
@@ -1103,6 +1164,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Subscription].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .id()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Subscription =
                 Subscription(checkRequired("id", id), additionalProperties.toImmutable())
         }
@@ -1230,6 +1303,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Threshold].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .value()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Threshold =
                 Threshold(checkRequired("value", value), additionalProperties.toImmutable())
         }

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForCustomerParams.kt

@@ -292,6 +292,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Body].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .currency()
+             * .type()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Body =
                 Body(
                     checkRequired("currency", currency),
@@ -518,6 +531,20 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AlertCreateForCustomerParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .customerId()
+         * .currency()
+         * .type()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AlertCreateForCustomerParams =
             AlertCreateForCustomerParams(
                 checkRequired("customerId", customerId),
@@ -737,6 +764,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Threshold].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .value()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Threshold =
                 Threshold(checkRequired("value", value), additionalProperties.toImmutable())
         }

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForExternalCustomerParams.kt

@@ -292,6 +292,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Body].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .currency()
+             * .type()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Body =
                 Body(
                     checkRequired("currency", currency),
@@ -524,6 +537,20 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AlertCreateForExternalCustomerParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .externalCustomerId()
+         * .currency()
+         * .type()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AlertCreateForExternalCustomerParams =
             AlertCreateForExternalCustomerParams(
                 checkRequired("externalCustomerId", externalCustomerId),
@@ -743,6 +770,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Threshold].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .value()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Threshold =
                 Threshold(checkRequired("value", value), additionalProperties.toImmutable())
         }

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForSubscriptionParams.kt

@@ -293,6 +293,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Body].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .thresholds()
+             * .type()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Body =
                 Body(
                     checkRequired("thresholds", thresholds).map { it.toImmutable() },
@@ -522,6 +535,20 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AlertCreateForSubscriptionParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .subscriptionId()
+         * .thresholds()
+         * .type()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AlertCreateForSubscriptionParams =
             AlertCreateForSubscriptionParams(
                 checkRequired("subscriptionId", subscriptionId),
@@ -637,6 +664,18 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Threshold].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .value()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Threshold =
                 Threshold(checkRequired("value", value), additionalProperties.toImmutable())
         }

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertDisableParams.kt

@@ -223,6 +223,18 @@ private constructor(
             keys.forEach(::removeAdditionalBodyProperty)
         }
 
+        /**
+         * Returns an immutable instance of [AlertDisableParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .alertConfigurationId()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AlertDisableParams =
             AlertDisableParams(
                 checkRequired("alertConfigurationId", alertConfigurationId),