chore: add KDoc documentation for API-related classes and methods

Author: OmarAlJarrah

.github/workflows/generate-publish-sdk.yaml

@@ -32,11 +32,11 @@ jobs:
           export KOTLIN_POST_PROCESS_FILE="npm run --prefix src/main/resources/post-processor process"
           gradle openApiGenerate
 
-      - name: Publish Snapshots
+      - name: Publish Snapshot
         working-directory: xap-sdk
         env:
           GPG_PASSPHRASE: ${{ secrets.GPG_PRIVATE_KEY_PASSPHRASE }}
           GPG_SECRET: ${{ secrets.GPG_PRIVATE_KEY }}
           SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
           SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
-        run: gradle publishSnapshots
+        run: gradle publishSnapshot

generator/tasks/lambdas.gradle.kts

@@ -56,25 +56,6 @@ ktlint {
         )
 }
 
-tasks.register("publishSnapshots") {
-    val snapshotModules =
-        rootProject.subprojects.filter { project ->
-            project.version.toString().contains("-SNAPSHOT") && project.tasks.names.contains("publish")
-        }
-
-    if (snapshotModules.isNotEmpty()) {
-        dependsOn(snapshotModules.map { ":${it.name}:publish" })
-    }
-
-    doLast {
-        if (snapshotModules.isEmpty()) {
-            println("❌ No snapshot modules to publish.")
-        } else {
-            println("📦 Successfully published snapshots for: ${snapshotModules.map { it.name }}")
-        }
-    }
-}
-
 apply("$rootDir/gradle-tasks/publish.gradle.kts")
 apply("$rootDir/gradle-tasks/signing.gradle.kts")
 apply("$rootDir/gradle-tasks/snapshot.gradle.kts")

xap-sdk/build.gradle.kts

@@ -13,6 +13,12 @@ import com.expediagroup.sdk.xap.configuration.XAP_OBJECT_MAPPER
 import com.expediagroup.sdk.xap.core.AsyncRequestExecutor
 import java.util.concurrent.CompletableFuture
 
+/**
+ * Asynchronous client for XAP API.
+ *
+ * @property apiEndpoint The API endpoint for XAP.
+ * @property restExecutor The executor for handling REST operations.
+ */
 class AsyncXapClient private constructor(
     config: AsyncXapClientConfiguration,
 ) : AsyncRestClient() {
@@ -25,15 +31,36 @@ class AsyncXapClient private constructor(
             requestExecutor = AsyncRequestExecutor(configuration = config),
         )
 
+    /**
+     * Executes an operation that does not expect a response body.
+     *
+     * @param operation The operation to execute.
+     * @return A CompletableFuture containing the response.
+     */
     fun execute(operation: OperationNoResponseBodyTrait): CompletableFuture<Response<Nothing?>> = restExecutor.execute(operation)
 
+    /**
+     * Executes an operation that expects a response body.
+     *
+     * @param T The type of the response body.
+     * @param operation The operation to execute.
+     * @return A CompletableFuture containing the response.
+     */
     fun <T : Any> execute(operation: JacksonModelOperationResponseBodyTrait<T>): CompletableFuture<Response<T>> = restExecutor.execute(operation)
 
     companion object {
+        /**
+         * Builder for creating an instance of [AsyncXapClient].
+         */
         class Builder : AsyncClientBuilder<AsyncXapClient>() {
             override fun build(): AsyncXapClient = AsyncXapClient(buildConfig())
         }
 
+        /**
+         * Creates a new builder for [AsyncXapClient].
+         *
+         * @return A new [Builder] instance.
+         */
         @JvmStatic
         fun builder() = Builder()
     }

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/client/AsyncXapClient.kt

@@ -13,6 +13,12 @@ import com.expediagroup.sdk.xap.configuration.XAP_OBJECT_MAPPER
 import com.expediagroup.sdk.xap.configuration.XapClientConfiguration
 import com.expediagroup.sdk.xap.core.RequestExecutor
 
+/**
+ * Synchronous client for XAP API.
+ *
+ * @property apiEndpoint The API endpoint for XAP.
+ * @property restExecutor The executor for handling REST operations.
+ */
 class XapClient private constructor(
     config: XapClientConfiguration,
 ) : RestClient() {
@@ -34,15 +40,36 @@ class XapClient private constructor(
                 ),
         )
 
+    /**
+     * Executes an operation that does not expect a response body.
+     *
+     * @param operation The operation to execute.
+     * @return The response of the operation.
+     */
     fun execute(operation: OperationNoResponseBodyTrait): Response<Nothing?> = restExecutor.execute(operation)
 
+    /**
+     * Executes an operation that expects a response body.
+     *
+     * @param T The type of the response body.
+     * @param operation The operation to execute.
+     * @return The response of the operation.
+     */
     fun <T : Any> execute(operation: JacksonModelOperationResponseBodyTrait<T>): Response<T> = restExecutor.execute(operation)
 
     companion object {
+        /**
+         * Builder for creating an instance of [XapClient].
+         */
         class Builder : ClientBuilder<XapClient>() {
             override fun build(): XapClient = XapClient(buildConfig())
         }
 
+        /**
+         * Creates a new builder for [XapClient].
+         *
+         * @return A new [Builder] instance.
+         */
         @JvmStatic
         fun builder() = Builder()
     }

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/client/XapClient.kt

@@ -1,5 +1,10 @@
 package com.expediagroup.sdk.xap.configuration
 
+/**
+ * Data class representing an API endpoint.
+ *
+ * @property endpoint The URL of the API endpoint.
+ */
 data class ApiEndpoint(
     val endpoint: String,
 )

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/configuration/ApiEndpoint.kt

@@ -1,5 +1,9 @@
 package com.expediagroup.sdk.xap.configuration
 
+/**
+ * Enum representing the client environment.
+ */
 enum class ClientEnvironment {
+    /** Production environment. */
     PROD,
 }

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/configuration/ClientEnvironment.kt

@@ -2,7 +2,17 @@ package com.expediagroup.sdk.xap.configuration
 
 import com.expediagroup.sdk.core.exception.client.ExpediaGroupConfigurationException
 
+/**
+ * Provides API endpoints based on the client environment.
+ */
 internal object EndpointProvider {
+    /**
+     * Retrieves the API endpoint for the given environment.
+     *
+     * @param environment The client environment. Defaults to [ClientEnvironment.PROD] if not specified.
+     * @return The [ApiEndpoint] for the specified environment.
+     * @throws ExpediaGroupConfigurationException If the environment is unsupported.
+     */
     fun getXapApiEndpoint(environment: ClientEnvironment? = null): ApiEndpoint {
         val env = environment ?: ClientEnvironment.PROD
 

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/configuration/EndpointProvider.kt

@@ -1,7 +1,13 @@
 package com.expediagroup.sdk.xap.configuration
 
+/**
+ * Enum representing the XAP API endpoints.
+ *
+ * @property url The URL of the API endpoint.
+ */
 enum class XapApiEndpoint(
     val url: String,
 ) {
+    /** Production environment endpoint. */
     PROD("https://apim.expedia.com"),
 }

xap-sdk/src/main/kotlin/com/expediagroup/sdk/xap/configuration/XapApiEndpoint.kt

@@ -5,36 +5,92 @@ import com.expediagroup.sdk.core.transport.Transport
 import com.expediagroup.sdk.rest.AsyncRestClient
 import com.expediagroup.sdk.rest.RestClient
 
+/**
+ * Configuration data class for XAP client.
+ *
+ * @property key The API key.
+ * @property secret The API secret.
+ * @property environment The client environment. Defaults to null.
+ * @property transport The transport mechanism. Defaults to null.
+ */
 data class XapClientConfiguration(
     val key: String,
     val secret: String,
     val environment: ClientEnvironment? = null,
     val transport: Transport? = null,
 )
 
+/**
+ * Configuration data class for asynchronous XAP client.
+ *
+ * @property key The API key.
+ * @property secret The API secret.
+ * @property environment The client environment. Defaults to null.
+ * @property asyncTransport The asynchronous transport mechanism. Defaults to null.
+ */
 data class AsyncXapClientConfiguration(
     val key: String,
     val secret: String,
     val environment: ClientEnvironment? = null,
     val asyncTransport: AsyncTransport? = null,
 )
 
+/**
+ * Abstract builder class for creating instances of [RestClient].
+ *
+ * @param T The type of [RestClient] to build.
+ */
 abstract class ClientBuilder<T : RestClient> {
     private var key: String? = null
     private var secret: String? = null
     private var environment: ClientEnvironment? = null
     private var transport: Transport? = null
 
+    /**
+     * Sets the API key.
+     *
+     * @param key The API key.
+     * @return The builder instance.
+     */
     fun key(key: String) = apply { this.key = key }
 
+    /**
+     * Sets the API secret.
+     *
+     * @param secret The API secret.
+     * @return The builder instance.
+     */
     fun secret(secret: String) = apply { this.secret = secret }
 
+    /**
+     * Sets the client environment.
+     *
+     * @param environment The client environment.
+     * @return The builder instance.
+     */
     fun environment(environment: ClientEnvironment) = apply { this.environment = environment }
 
+    /**
+     * Sets the transport mechanism.
+     *
+     * @param transport The transport mechanism.
+     * @return The builder instance.
+     */
     fun transport(transport: Transport) = apply { this.transport = transport }
 
+    /**
+     * Builds the [RestClient] instance.
+     *
+     * @return The built [RestClient] instance.
+     */
     abstract fun build(): T
 
+    /**
+     * Builds the configuration for the XAP client.
+     *
+     * @return The built [XapClientConfiguration] instance.
+     * @throws IllegalArgumentException If the key or secret is not provided.
+     */
     protected fun buildConfig(): XapClientConfiguration {
         require(key != null) {
             "key is required"
@@ -53,22 +109,62 @@ abstract class ClientBuilder<T : RestClient> {
     }
 }
 
+/**
+ * Abstract builder class for creating instances of [AsyncRestClient].
+ *
+ * @param T The type of [AsyncRestClient] to build.
+ */
 abstract class AsyncClientBuilder<T : AsyncRestClient> {
     private var key: String? = null
     private var secret: String? = null
     private var environment: ClientEnvironment? = null
     private var asyncTransport: AsyncTransport? = null
 
+    /**
+     * Sets the API key.
+     *
+     * @param key The API key.
+     * @return The builder instance.
+     */
     fun key(key: String) = apply { this.key = key }
 
+    /**
+     * Sets the API secret.
+     *
+     * @param secret The API secret.
+     * @return The builder instance.
+     */
     fun secret(secret: String) = apply { this.secret = secret }
 
+    /**
+     * Sets the client environment.
+     *
+     * @param environment The client environment.
+     * @return The builder instance.
+     */
     fun environment(environment: ClientEnvironment) = apply { this.environment = environment }
 
+    /**
+     * Sets the asynchronous transport mechanism.
+     *
+     * @param asyncTransport The asynchronous transport mechanism.
+     * @return The builder instance.
+     */
     fun asyncTransport(asyncTransport: AsyncTransport) = apply { this.asyncTransport = asyncTransport }
 
+    /**
+     * Builds the [AsyncRestClient] instance.
+     *
+     * @return The built [AsyncRestClient] instance.
+     */
     abstract fun build(): T
 
+    /**
+     * Builds the configuration for the asynchronous XAP client.
+     *
+     * @return The built [AsyncXapClientConfiguration] instance.
+     * @throws IllegalArgumentException If the key or secret is not provided.
+     */
     protected fun buildConfig(): AsyncXapClientConfiguration {
         require(key != null) {
             "key is required"