docs: deduplicate and refine comments

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

@@ -146,6 +146,7 @@ class BraintrustOkHttpClient private constructor() {
 
         fun apiKey(apiKey: String?) = apply { clientOptions.apiKey(apiKey) }
 
+        /** Alias for calling [Builder.apiKey] with `apiKey.orElse(null)`. */
         fun apiKey(apiKey: Optional<String>) = apiKey(apiKey.getOrNull())
 
         fun fromEnv() = apply { clientOptions.fromEnv() }

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

@@ -148,6 +148,7 @@ class BraintrustOkHttpClientAsync private constructor() {
 
         fun apiKey(apiKey: String?) = apply { clientOptions.apiKey(apiKey) }
 
+        /** Alias for calling [Builder.apiKey] with `apiKey.orElse(null)`. */
         fun apiKey(apiKey: Optional<String>) = apiKey(apiKey.getOrNull())
 
         fun fromEnv() = apply { clientOptions.fromEnv() }

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

@@ -94,6 +94,7 @@ private constructor(
 
         fun apiKey(apiKey: String?) = apply { this.apiKey = apiKey }
 
+        /** Alias for calling [Builder.apiKey] with `apiKey.orElse(null)`. */
         fun apiKey(apiKey: Optional<String>) = apiKey(apiKey.getOrNull())
 
         fun headers(headers: Headers) = apply {

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

@@ -90,13 +90,7 @@ private constructor(
          */
         fun connect(connect: Duration?) = apply { this.connect = connect }
 
-        /**
-         * The maximum time allowed to establish a connection with a host.
-         *
-         * A value of [Duration.ZERO] means there's no timeout.
-         *
-         * Defaults to `Duration.ofMinutes(1)`.
-         */
+        /** Alias for calling [Builder.connect] with `connect.orElse(null)`. */
         fun connect(connect: Optional<Duration>) = connect(connect.getOrNull())
 
         /**
@@ -108,13 +102,7 @@ private constructor(
          */
         fun read(read: Duration?) = apply { this.read = read }
 
-        /**
-         * The maximum time allowed between two data packets when waiting for the server’s response.
-         *
-         * A value of [Duration.ZERO] means there's no timeout.
-         *
-         * Defaults to `request()`.
-         */
+        /** Alias for calling [Builder.read] with `read.orElse(null)`. */
         fun read(read: Optional<Duration>) = read(read.getOrNull())
 
         /**
@@ -126,13 +114,7 @@ private constructor(
          */
         fun write(write: Duration?) = apply { this.write = write }
 
-        /**
-         * The maximum time allowed between two data packets when sending the request to the server.
-         *
-         * A value of [Duration.ZERO] means there's no timeout.
-         *
-         * Defaults to `request()`.
-         */
+        /** Alias for calling [Builder.write] with `write.orElse(null)`. */
         fun write(write: Optional<Duration>) = write(write.getOrNull())
 
         /**
@@ -147,16 +129,7 @@ private constructor(
          */
         fun request(request: Duration?) = apply { this.request = request }
 
-        /**
-         * The maximum time allowed for a complete HTTP call, not including retries.
-         *
-         * This includes resolving DNS, connecting, writing the request body, server processing, as
-         * well as reading the response body.
-         *
-         * A value of [Duration.ZERO] means there's no timeout.
-         *
-         * Defaults to `Duration.ofMinutes(1)`.
-         */
+        /** Alias for calling [Builder.request] with `request.orElse(null)`. */
         fun request(request: Optional<Duration>) = request(request.getOrNull())
 
         fun build(): Timeout = Timeout(connect, read, write, request)

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

@@ -10,6 +10,7 @@ import com.braintrustdata.api.core.NoAutoDetect
 import com.braintrustdata.api.core.checkRequired
 import com.braintrustdata.api.core.immutableEmptyMap
 import com.braintrustdata.api.core.toImmutable
+import com.braintrustdata.api.errors.BraintrustInvalidDataException
 import com.fasterxml.jackson.annotation.JsonAnyGetter
 import com.fasterxml.jackson.annotation.JsonAnySetter
 import com.fasterxml.jackson.annotation.JsonCreator
@@ -42,50 +43,122 @@ private constructor(
     @JsonAnySetter private val additionalProperties: Map<String, JsonValue> = immutableEmptyMap(),
 ) {
 
-    /** Unique identifier for the AI secret */
+    /**
+     * Unique identifier for the AI secret
+     *
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type or is
+     *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+     */
     fun id(): String = id.getRequired("id")
 
-    /** Name of the AI secret */
+    /**
+     * Name of the AI secret
+     *
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type or is
+     *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+     */
     fun name(): String = name.getRequired("name")
 
-    /** Unique identifier for the organization */
+    /**
+     * Unique identifier for the organization
+     *
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type or is
+     *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+     */
     fun orgId(): String = orgId.getRequired("org_id")
 
-    /** Date of AI secret creation */
+    /**
+     * Date of AI secret creation
+     *
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
     fun created(): Optional<OffsetDateTime> = Optional.ofNullable(created.getNullable("created"))
 
+    /**
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
     fun metadata(): Optional<Metadata> = Optional.ofNullable(metadata.getNullable("metadata"))
 
+    /**
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
     fun previewSecret(): Optional<String> =
         Optional.ofNullable(previewSecret.getNullable("preview_secret"))
 
+    /**
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
     fun type(): Optional<String> = Optional.ofNullable(type.getNullable("type"))
 
-    /** Date of last AI secret update */
+    /**
+     * Date of last AI secret update
+     *
+     * @throws BraintrustInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
     fun updatedAt(): Optional<OffsetDateTime> =
         Optional.ofNullable(updatedAt.getNullable("updated_at"))
 
-    /** Unique identifier for the AI secret */
+    /**
+     * Returns the raw JSON value of [id].
+     *
+     * Unlike [id], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("id") @ExcludeMissing fun _id(): JsonField<String> = id
 
-    /** Name of the AI secret */
+    /**
+     * Returns the raw JSON value of [name].
+     *
+     * Unlike [name], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("name") @ExcludeMissing fun _name(): JsonField<String> = name
 
-    /** Unique identifier for the organization */
+    /**
+     * Returns the raw JSON value of [orgId].
+     *
+     * Unlike [orgId], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("org_id") @ExcludeMissing fun _orgId(): JsonField<String> = orgId
 
-    /** Date of AI secret creation */
+    /**
+     * Returns the raw JSON value of [created].
+     *
+     * Unlike [created], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("created") @ExcludeMissing fun _created(): JsonField<OffsetDateTime> = created
 
+    /**
+     * Returns the raw JSON value of [metadata].
+     *
+     * Unlike [metadata], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("metadata") @ExcludeMissing fun _metadata(): JsonField<Metadata> = metadata
 
+    /**
+     * Returns the raw JSON value of [previewSecret].
+     *
+     * Unlike [previewSecret], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("preview_secret")
     @ExcludeMissing
     fun _previewSecret(): JsonField<String> = previewSecret
 
+    /**
+     * Returns the raw JSON value of [type].
+     *
+     * Unlike [type], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("type") @ExcludeMissing fun _type(): JsonField<String> = type
 
-    /** Date of last AI secret update */
+    /**
+     * Returns the raw JSON value of [updatedAt].
+     *
+     * Unlike [updatedAt], this method doesn't throw if the JSON field has an unexpected type.
+     */
     @JsonProperty("updated_at")
     @ExcludeMissing
     fun _updatedAt(): JsonField<OffsetDateTime> = updatedAt
@@ -158,59 +231,109 @@ private constructor(
         /** Unique identifier for the AI secret */
         fun id(id: String) = id(JsonField.of(id))
 
-        /** Unique identifier for the AI secret */
+        /**
+         * Sets [Builder.id] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.id] with a well-typed [String] value instead. This
+         * method is primarily for setting the field to an undocumented or not yet supported value.
+         */
         fun id(id: JsonField<String>) = apply { this.id = id }
 
         /** Name of the AI secret */
         fun name(name: String) = name(JsonField.of(name))
 
-        /** Name of the AI secret */
+        /**
+         * Sets [Builder.name] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.name] with a well-typed [String] value instead. This
+         * method is primarily for setting the field to an undocumented or not yet supported value.
+         */
         fun name(name: JsonField<String>) = apply { this.name = name }
 
         /** Unique identifier for the organization */
         fun orgId(orgId: String) = orgId(JsonField.of(orgId))
 
-        /** Unique identifier for the organization */
+        /**
+         * Sets [Builder.orgId] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.orgId] with a well-typed [String] value instead. This
+         * method is primarily for setting the field to an undocumented or not yet supported value.
+         */
         fun orgId(orgId: JsonField<String>) = apply { this.orgId = orgId }
 
         /** Date of AI secret creation */
         fun created(created: OffsetDateTime?) = created(JsonField.ofNullable(created))
 
-        /** Date of AI secret creation */
+        /** Alias for calling [Builder.created] with `created.orElse(null)`. */
         fun created(created: Optional<OffsetDateTime>) = created(created.getOrNull())
 
-        /** Date of AI secret creation */
+        /**
+         * Sets [Builder.created] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.created] with a well-typed [OffsetDateTime] value
+         * instead. This method is primarily for setting the field to an undocumented or not yet
+         * supported value.
+         */
         fun created(created: JsonField<OffsetDateTime>) = apply { this.created = created }
 
         fun metadata(metadata: Metadata?) = metadata(JsonField.ofNullable(metadata))
 
+        /** Alias for calling [Builder.metadata] with `metadata.orElse(null)`. */
         fun metadata(metadata: Optional<Metadata>) = metadata(metadata.getOrNull())
 
+        /**
+         * Sets [Builder.metadata] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.metadata] with a well-typed [Metadata] value instead.
+         * This method is primarily for setting the field to an undocumented or not yet supported
+         * value.
+         */
         fun metadata(metadata: JsonField<Metadata>) = apply { this.metadata = metadata }
 
         fun previewSecret(previewSecret: String?) =
             previewSecret(JsonField.ofNullable(previewSecret))
 
+        /** Alias for calling [Builder.previewSecret] with `previewSecret.orElse(null)`. */
         fun previewSecret(previewSecret: Optional<String>) =
             previewSecret(previewSecret.getOrNull())
 
+        /**
+         * Sets [Builder.previewSecret] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.previewSecret] with a well-typed [String] value instead.
+         * This method is primarily for setting the field to an undocumented or not yet supported
+         * value.
+         */
         fun previewSecret(previewSecret: JsonField<String>) = apply {
             this.previewSecret = previewSecret
         }
 
         fun type(type: String?) = type(JsonField.ofNullable(type))
 
+        /** Alias for calling [Builder.type] with `type.orElse(null)`. */
         fun type(type: Optional<String>) = type(type.getOrNull())
 
+        /**
+         * Sets [Builder.type] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.type] with a well-typed [String] value instead. This
+         * method is primarily for setting the field to an undocumented or not yet supported value.
+         */
         fun type(type: JsonField<String>) = apply { this.type = type }
 
         /** Date of last AI secret update */
         fun updatedAt(updatedAt: OffsetDateTime?) = updatedAt(JsonField.ofNullable(updatedAt))
 
-        /** Date of last AI secret update */
+        /** Alias for calling [Builder.updatedAt] with `updatedAt.orElse(null)`. */
         fun updatedAt(updatedAt: Optional<OffsetDateTime>) = updatedAt(updatedAt.getOrNull())
 
-        /** Date of last AI secret update */
+        /**
+         * Sets [Builder.updatedAt] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.updatedAt] with a well-typed [OffsetDateTime] value
+         * instead. This method is primarily for setting the field to an undocumented or not yet
+         * supported value.
+         */
         fun updatedAt(updatedAt: JsonField<OffsetDateTime>) = apply { this.updatedAt = updatedAt }
 
         fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {