docs: add build method comments

braintrust-java-client-okhttp/src/main/kotlin/com/braintrustdata/api/client/okhttp/BraintrustOkHttpClient.kt

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

braintrust-java-client-okhttp/src/main/kotlin/com/braintrustdata/api/client/okhttp/BraintrustOkHttpClientAsync.kt

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

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

@@ -179,6 +179,18 @@ private constructor(
 
         fun fromEnv() = apply { System.getenv("BRAINTRUST_API_KEY")?.let { apiKey(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()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): ClientOptions {
             val httpClient = checkRequired("httpClient", httpClient)
 

braintrust-java-core/src/main/kotlin/com/braintrustdata/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)
     }
 

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/errors/BraintrustError.kt

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

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AISecret.kt

@@ -355,6 +355,20 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [AISecret].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .id()
+         * .name()
+         * .orgId()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AISecret =
             AISecret(
                 checkRequired("id", id),
@@ -428,6 +442,11 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Metadata].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             */
             fun build(): Metadata = Metadata(additionalProperties.toImmutable())
         }
 

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/Acl.kt

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

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclBatchUpdateParams.kt

@@ -288,6 +288,11 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Body].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             */
             fun build(): Body =
                 Body(
                     (addAcls ?: JsonMissing.of()).map { it.toImmutable() },
@@ -520,6 +525,11 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AclBatchUpdateParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): AclBatchUpdateParams =
             AclBatchUpdateParams(
                 body.build(),
@@ -888,6 +898,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [AddAcl].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .objectId()
+             * .objectType()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): AddAcl =
                 AddAcl(
                     checkRequired("objectId", objectId),
@@ -1279,6 +1302,19 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [RemoveAcl].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```java
+             * .objectId()
+             * .objectType()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): RemoveAcl =
                 RemoveAcl(
                     checkRequired("objectId", objectId),

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclBatchUpdateResponse.kt

@@ -212,6 +212,19 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [AclBatchUpdateResponse].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .addedAcls()
+         * .removedAcls()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AclBatchUpdateResponse =
             AclBatchUpdateResponse(
                 checkRequired("addedAcls", addedAcls).map { it.toImmutable() },

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclCreateParams.kt

@@ -512,6 +512,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
+             * .objectId()
+             * .objectType()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Body =
                 Body(
                     checkRequired("objectId", objectId),
@@ -804,6 +817,19 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AclCreateParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .objectId()
+         * .objectType()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AclCreateParams =
             AclCreateParams(body.build(), additionalHeaders.build(), additionalQueryParams.build())
     }

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclDeleteParams.kt

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

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclFindAndDeleteParams.kt

@@ -509,6 +509,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
+             * .objectId()
+             * .objectType()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Body =
                 Body(
                     checkRequired("objectId", objectId),
@@ -801,6 +814,19 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AclFindAndDeleteParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .objectId()
+         * .objectType()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AclFindAndDeleteParams =
             AclFindAndDeleteParams(
                 body.build(),

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclListPage.kt

@@ -150,7 +150,12 @@ private constructor(
                 this.additionalProperties.put(key, value)
             }
 
-            fun build() = Response(objects, additionalProperties.toImmutable())
+            /**
+             * Returns an immutable instance of [Response].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             */
+            fun build(): Response = Response(objects, additionalProperties.toImmutable())
         }
     }
 

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclListPageAsync.kt

@@ -152,7 +152,12 @@ private constructor(
                 this.additionalProperties.put(key, value)
             }
 
-            fun build() = Response(objects, additionalProperties.toImmutable())
+            /**
+             * Returns an immutable instance of [Response].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             */
+            fun build(): Response = Response(objects, additionalProperties.toImmutable())
         }
     }
 

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclListParams.kt

@@ -288,6 +288,19 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AclListParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .objectId()
+         * .objectType()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AclListParams =
             AclListParams(
                 checkRequired("objectId", objectId),

braintrust-java-core/src/main/kotlin/com/braintrustdata/api/models/AclRetrieveParams.kt

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