Merge pull request #87 from OneBusAway/release-please--branches--main--changes--next

release: 0.1.0-alpha.31

Author: Ahmedhossamdev

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.30"
+  ".": "0.1.0-alpha.31"
 }

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.0-alpha.31 (2025-07-25)
+
+Full Changelog: [v0.1.0-alpha.30...v0.1.0-alpha.31](https://github.com/OneBusAway/java-sdk/compare/v0.1.0-alpha.30...v0.1.0-alpha.31)
+
+### Chores
+
+* **internal:** remove unnecessary `[...]` in `[@see](https://github.com/see)` ([bb19ff1](https://github.com/OneBusAway/java-sdk/commit/bb19ff1cd43642f3023f3e521509c424142e9f36))
+
+
+### Documentation
+
+* more code comments ([07cd62d](https://github.com/OneBusAway/java-sdk/commit/07cd62d5e4d6479f61961f0e75eb3a507fd4516c))
+
 ## 0.1.0-alpha.30 (2025-07-24)
 
 Full Changelog: [v0.1.0-alpha.29...v0.1.0-alpha.30](https://github.com/OneBusAway/java-sdk/compare/v0.1.0-alpha.29...v0.1.0-alpha.30)

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/org.onebusaway/onebusaway-sdk-java)](https://central.sonatype.com/artifact/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.30)
-[![javadoc](https://javadoc.io/badge2/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.30/javadoc.svg)](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.30)
+[![Maven Central](https://img.shields.io/maven-central/v/org.onebusaway/onebusaway-sdk-java)](https://central.sonatype.com/artifact/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.31)
+[![javadoc](https://javadoc.io/badge2/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.31/javadoc.svg)](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.31)
 
 <!-- x-release-please-end -->
 
@@ -15,7 +15,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [developer.onebusaway.org](https://developer.onebusaway.org). Javadocs are available on [javadoc.io](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.30).
+The REST API documentation can be found on [developer.onebusaway.org](https://developer.onebusaway.org). Javadocs are available on [javadoc.io](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-java/0.1.0-alpha.31).
 
 <!-- x-release-please-end -->
 
@@ -26,7 +26,7 @@ The REST API documentation can be found on [developer.onebusaway.org](https://de
 ### Gradle
 
 ```kotlin
-implementation("org.onebusaway:onebusaway-sdk-java:0.1.0-alpha.30")
+implementation("org.onebusaway:onebusaway-sdk-java:0.1.0-alpha.31")
 ```
 
 ### Maven
@@ -35,7 +35,7 @@ implementation("org.onebusaway:onebusaway-sdk-java:0.1.0-alpha.30")
 <dependency>
   <groupId>org.onebusaway</groupId>
   <artifactId>onebusaway-sdk-java</artifactId>
-  <version>0.1.0-alpha.30</version>
+  <version>0.1.0-alpha.31</version>
 </dependency>
 ```
 
@@ -256,7 +256,7 @@ If the SDK threw an exception, but you're _certain_ the version is compatible, t
 
 ### Retries
 
-The SDK automatically retries 2 times by default, with a short exponential backoff.
+The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
 
 Only the following error types are retried:
 
@@ -266,7 +266,7 @@ Only the following error types are retried:
 - 429 Rate Limit
 - 5xx Internal
 
-The API may also explicitly instruct the SDK to retry or not retry a response.
+The API may also explicitly instruct the SDK to retry or not retry a request.
 
 To set a custom number of retries, configure the client using the `maxRetries` method:
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "org.onebusaway"
-    version = "0.1.0-alpha.30" // x-release-please-version
+    version = "0.1.0-alpha.31" // x-release-please-version
 }
 
 subprojects {

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

@@ -16,18 +16,26 @@ import org.onebusaway.client.OnebusawaySdkClientImpl
 import org.onebusaway.core.ClientOptions
 import org.onebusaway.core.Timeout
 import org.onebusaway.core.http.Headers
+import org.onebusaway.core.http.HttpClient
 import org.onebusaway.core.http.QueryParams
 import org.onebusaway.core.jsonMapper
 
+/**
+ * A class that allows building an instance of [OnebusawaySdkClient] with [OkHttpClient] as the
+ * underlying [HttpClient].
+ */
 class OnebusawaySdkOkHttpClient private constructor() {
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [OnebusawaySdkOkHttpClient].
-         */
+        /** Returns a mutable builder for constructing an instance of [OnebusawaySdkClient]. */
         @JvmStatic fun builder() = Builder()
 
+        /**
+         * Returns a client configured using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         @JvmStatic fun fromEnv(): OnebusawaySdkClient = builder().fromEnv().build()
     }
 
@@ -104,19 +112,49 @@ class OnebusawaySdkOkHttpClient private constructor() {
             clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
         }
 
+        /**
+         * The Jackson JSON mapper to use for serializing and deserializing JSON.
+         *
+         * Defaults to [org.onebusaway.core.jsonMapper]. The default is usually sufficient and
+         * rarely needs to be overridden.
+         */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The clock to use for operations that require timing, like retries.
+         *
+         * This is primarily useful for using a fake clock in tests.
+         *
+         * Defaults to [Clock.systemUTC].
+         */
         fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
 
+        /**
+         * The base URL to use for every request.
+         *
+         * Defaults to the production environment: `https://api.pugetsound.onebusaway.org`.
+         */
         fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
 
         /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
         fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
 
+        /**
+         * Whether to call `validate` on every response before returning it.
+         *
+         * Defaults to false, which means the shape of the response will not be validated upfront.
+         * Instead, validation will only occur for the parts of the response that are accessed.
+         */
         fun responseValidation(responseValidation: Boolean) = apply {
             clientOptions.responseValidation(responseValidation)
         }
 
+        /**
+         * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+         * retries.
+         *
+         * Defaults to [Timeout.default].
+         */
         fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
 
         /**
@@ -128,6 +166,21 @@ class OnebusawaySdkOkHttpClient private constructor() {
          */
         fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
 
+        /**
+         * The maximum number of times to retry failed requests, with a short exponential backoff
+         * between requests.
+         *
+         * Only the following error types are retried:
+         * - Connection errors (for example, due to a network connectivity problem)
+         * - 408 Request Timeout
+         * - 409 Conflict
+         * - 429 Rate Limit
+         * - 5xx Internal
+         *
+         * The API may also explicitly instruct the SDK to retry or not retry a request.
+         *
+         * Defaults to 2.
+         */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -212,6 +265,11 @@ class OnebusawaySdkOkHttpClient private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
+        /**
+         * Updates configuration using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         /**

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

@@ -16,19 +16,26 @@ import org.onebusaway.client.OnebusawaySdkClientAsyncImpl
 import org.onebusaway.core.ClientOptions
 import org.onebusaway.core.Timeout
 import org.onebusaway.core.http.Headers
+import org.onebusaway.core.http.HttpClient
 import org.onebusaway.core.http.QueryParams
 import org.onebusaway.core.jsonMapper
 
+/**
+ * A class that allows building an instance of [OnebusawaySdkClientAsync] with [OkHttpClient] as the
+ * underlying [HttpClient].
+ */
 class OnebusawaySdkOkHttpClientAsync private constructor() {
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of
-         * [OnebusawaySdkOkHttpClientAsync].
-         */
+        /** Returns a mutable builder for constructing an instance of [OnebusawaySdkClientAsync]. */
         @JvmStatic fun builder() = Builder()
 
+        /**
+         * Returns a client configured using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         @JvmStatic fun fromEnv(): OnebusawaySdkClientAsync = builder().fromEnv().build()
     }
 
@@ -105,19 +112,49 @@ class OnebusawaySdkOkHttpClientAsync private constructor() {
             clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
         }
 
+        /**
+         * The Jackson JSON mapper to use for serializing and deserializing JSON.
+         *
+         * Defaults to [org.onebusaway.core.jsonMapper]. The default is usually sufficient and
+         * rarely needs to be overridden.
+         */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The clock to use for operations that require timing, like retries.
+         *
+         * This is primarily useful for using a fake clock in tests.
+         *
+         * Defaults to [Clock.systemUTC].
+         */
         fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
 
+        /**
+         * The base URL to use for every request.
+         *
+         * Defaults to the production environment: `https://api.pugetsound.onebusaway.org`.
+         */
         fun baseUrl(baseUrl: String?) = apply { clientOptions.baseUrl(baseUrl) }
 
         /** Alias for calling [Builder.baseUrl] with `baseUrl.orElse(null)`. */
         fun baseUrl(baseUrl: Optional<String>) = baseUrl(baseUrl.getOrNull())
 
+        /**
+         * Whether to call `validate` on every response before returning it.
+         *
+         * Defaults to false, which means the shape of the response will not be validated upfront.
+         * Instead, validation will only occur for the parts of the response that are accessed.
+         */
         fun responseValidation(responseValidation: Boolean) = apply {
             clientOptions.responseValidation(responseValidation)
         }
 
+        /**
+         * Sets the maximum time allowed for various parts of an HTTP call's lifecycle, excluding
+         * retries.
+         *
+         * Defaults to [Timeout.default].
+         */
         fun timeout(timeout: Timeout) = apply { clientOptions.timeout(timeout) }
 
         /**
@@ -129,6 +166,21 @@ class OnebusawaySdkOkHttpClientAsync private constructor() {
          */
         fun timeout(timeout: Duration) = apply { clientOptions.timeout(timeout) }
 
+        /**
+         * The maximum number of times to retry failed requests, with a short exponential backoff
+         * between requests.
+         *
+         * Only the following error types are retried:
+         * - Connection errors (for example, due to a network connectivity problem)
+         * - 408 Request Timeout
+         * - 409 Conflict
+         * - 429 Rate Limit
+         * - 5xx Internal
+         *
+         * The API may also explicitly instruct the SDK to retry or not retry a request.
+         *
+         * Defaults to 2.
+         */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
@@ -213,6 +265,11 @@ class OnebusawaySdkOkHttpClientAsync private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
+        /**
+         * Updates configuration using system properties and environment variables.
+         *
+         * @see ClientOptions.Builder.fromEnv
+         */
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         /**