docs: add build method comments

onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt

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

onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt

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

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/ClientOptions.kt

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

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/Timeout.kt

@@ -117,6 +117,11 @@ private constructor(
          */
         fun request(request: Duration?) = apply { this.request = request }
 
+        /**
+         * 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)
     }
 

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/errors/OnebusawaySdkError.kt

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

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/models/AgenciesWithCoverageListParams.kt

@@ -149,6 +149,11 @@ private constructor(
             additionalQueryParams.removeAll(keys)
         }
 
+        /**
+         * Returns an immutable instance of [AgenciesWithCoverageListParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         */
         fun build(): AgenciesWithCoverageListParams =
             AgenciesWithCoverageListParams(additionalHeaders.build(), additionalQueryParams.build())
     }

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/models/AgenciesWithCoverageListResponse.kt

@@ -237,6 +237,22 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [AgenciesWithCoverageListResponse].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```kotlin
+         * .code()
+         * .currentTime()
+         * .text()
+         * .version()
+         * .data()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AgenciesWithCoverageListResponse =
             AgenciesWithCoverageListResponse(
                 checkRequired("code", code),
@@ -428,6 +444,20 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Data].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```kotlin
+             * .limitExceeded()
+             * .list()
+             * .references()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Data =
                 Data(
                     checkRequired("limitExceeded", limitExceeded),
@@ -665,6 +695,22 @@ private constructor(
                     keys.forEach(::removeAdditionalProperty)
                 }
 
+                /**
+                 * Returns an immutable instance of [List].
+                 *
+                 * Further updates to this [Builder] will not mutate the returned instance.
+                 *
+                 * The following fields are required:
+                 * ```kotlin
+                 * .agencyId()
+                 * .lat()
+                 * .latSpan()
+                 * .lon()
+                 * .lonSpan()
+                 * ```
+                 *
+                 * @throws IllegalStateException if any required field is unset.
+                 */
                 fun build(): List =
                     List(
                         checkRequired("agencyId", agencyId),

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/models/AgencyRetrieveParams.kt

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

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/models/AgencyRetrieveResponse.kt

@@ -233,6 +233,22 @@ private constructor(
             keys.forEach(::removeAdditionalProperty)
         }
 
+        /**
+         * Returns an immutable instance of [AgencyRetrieveResponse].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```kotlin
+         * .code()
+         * .currentTime()
+         * .text()
+         * .version()
+         * .data()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
         fun build(): AgencyRetrieveResponse =
             AgencyRetrieveResponse(
                 checkRequired("code", code),
@@ -410,6 +426,20 @@ private constructor(
                 keys.forEach(::removeAdditionalProperty)
             }
 
+            /**
+             * Returns an immutable instance of [Data].
+             *
+             * Further updates to this [Builder] will not mutate the returned instance.
+             *
+             * The following fields are required:
+             * ```kotlin
+             * .entry()
+             * .limitExceeded()
+             * .references()
+             * ```
+             *
+             * @throws IllegalStateException if any required field is unset.
+             */
             fun build(): Data =
                 Data(
                     checkRequired("entry", entry),
@@ -806,6 +836,21 @@ private constructor(
                     keys.forEach(::removeAdditionalProperty)
                 }
 
+                /**
+                 * Returns an immutable instance of [Entry].
+                 *
+                 * Further updates to this [Builder] will not mutate the returned instance.
+                 *
+                 * The following fields are required:
+                 * ```kotlin
+                 * .id()
+                 * .name()
+                 * .timezone()
+                 * .url()
+                 * ```
+                 *
+                 * @throws IllegalStateException if any required field is unset.
+                 */
                 fun build(): Entry =
                     Entry(
                         checkRequired("id", id),

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/models/ArrivalAndDepartureListParams.kt

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