docs: Write dokka doc (#128)

* refactor: sagaManager's sync... method to ...sync

* docs: Write dokka doc

build.gradle

@@ -2,6 +2,7 @@ import org.springframework.boot.gradle.plugin.SpringBootPlugin
 
 plugins {
     id "application"
+    id 'org.jetbrains.dokka' version "${dokkaVersion}"
     id "org.jetbrains.kotlin.jvm" version "${jetbrainKotlinVersion}"
     id "org.jetbrains.kotlin.plugin.spring" version "${jetbrainKotlinVersion}"
     id "org.springframework.boot" version "${springbootVersion}" apply false
@@ -50,6 +51,7 @@ apply from: "gradle/core.gradle"
 apply from: "gradle/sonar.gradle"
 apply from: "gradle/kotlin.gradle"
 apply from: "gradle/spring.gradle"
+apply from: "gradle/docs.gradle"
 
 wrapper {
     gradleVersion = "7.6.1"

gradle.properties

@@ -18,6 +18,7 @@ springMockkVersion=4.0.0
 
 ### Kotlin ###
 jetbrainKotlinVersion=1.9.22
+dokkaVersion=1.9.20
 jvmTarget=17
 
 ### Kotest ###

gradle/docs.gradle

@@ -0,0 +1,19 @@
+dokkaHtml {
+    outputDirectory.set(file("build/documentation/html"))
+}
+
+dokkaGfm {
+    outputDirectory.set(file("build/documentation/markdown"))
+}
+
+tasks.register('dokkaHtmlJar', Jar.class) {
+    dependsOn(dokkaHtml)
+    from(dokkaHtml)
+    archiveClassifier.set("html-docs")
+}
+
+tasks.register('dokkaJavadocJar', Jar.class) {
+    dependsOn(dokkaJavadoc)
+    from(dokkaJavadoc)
+    archiveClassifier.set("javadoc")
+}

src/main/kotlin/org/rooftop/netx/api/Context.kt

@@ -1,23 +1,61 @@
 package org.rooftop.netx.api
 
+import org.rooftop.netx.core.Codec
 import kotlin.reflect.KClass
 
+/**
+ * Context maintained in each saga.
+ *
+ * The lifecycle of the Context is per saga request.
+ *
+ * @see Orchestrator
+ * @see ContextOrchestrate
+ * @see ContextRollback
+ */
 data class Context internal constructor(
     private val codec: Codec,
     internal val contexts: MutableMap<String, String>,
 ) {
 
+    /**
+     * Sets the value with the specified key in the Context.
+     *
+     * Once set, it can be used in subsequent orchestrate and rollback operations.
+     *
+     * If the key already exists, it will overwrite the value.
+     */
     fun <T : Any> set(key: String, value: T) {
         contexts[key] = codec.encode(value)
     }
 
+    /**
+     * Decodes the value associated with the key using the provided type reference.
+     *
+     * Use TypeReference when decoding types with generics.
+     *
+     * Example.
+     *
+     *      context.decodeContext("foos", object: TypeReference<List<Foo>>(){})
+     *
+     * @param typeReference
+     * @param T
+     */
     fun <T : Any> decodeContext(key: String, typeReference: TypeReference<T>): T =
         contexts[key]?.let {
             codec.decode(it, typeReference)
         } ?: throw NullPointerException("Cannot find context by key \"$key\"")
 
+    /**
+     * Decodes the value associated with the key using the provided Class.
+     *
+     * @param type
+     * @param T
+     */
     fun <T : Any> decodeContext(key: String, type: Class<T>): T = decodeContext(key, type.kotlin)
 
+    /**
+     * @see decodeContext
+     */
     fun <T : Any> decodeContext(key: String, type: KClass<T>): T = contexts[key]?.let {
         codec.decode(it, type)
     } ?: throw NullPointerException("Cannot find context by key \"$key\"")

src/main/kotlin/org/rooftop/netx/api/ContextOrchestrate.kt

@@ -1,8 +1,23 @@
 package org.rooftop.netx.api
 
+/**
+ * An interface for accessing the Context maintained in each Orchestrator saga.
+ *
+ * @see Orchestrate
+ * @see Context
+ * @see Orchestrator
+ */
 fun interface ContextOrchestrate<T : Any, V : Any> : TypeReified<T> {
 
+    /**
+     * Passes the context with the request to orchestrate.
+     *
+     * @see Orchestrate.orchestrate
+     */
     fun orchestrate(context: Context, request: T): V
 
+    /**
+     * @see Orchestrate.reified
+     */
     override fun reified(): TypeReference<T>? = null
 }

src/main/kotlin/org/rooftop/netx/api/ContextRollback.kt

@@ -1,8 +1,23 @@
 package org.rooftop.netx.api
 
+/**
+ * An interface for accessing the Context maintained in each Orchestrator saga.
+ *
+ * @see Orchestrate
+ * @see Context
+ * @see Orchestrator
+ */
 fun interface ContextRollback<T : Any, V : Any?> : TypeReified<T> {
 
+    /**
+     * Passes the context with the request to orchestrate.
+     *
+     * @see Rollback.rollback
+     */
     fun rollback(context: Context, request: T): V
 
+    /**
+     * @see Rollback.reified
+     */
     override fun reified(): TypeReference<T>? = null
 }

src/main/kotlin/org/rooftop/netx/api/Orchestrate.kt

@@ -1,8 +1,28 @@
 package org.rooftop.netx.api
 
+/**
+ * Unit of operation for Orchestrator.
+ *
+ * Orchestrate is guaranteed to be executed at least once under any circumstances.
+ *
+ * @see Orchestrator
+ */
 fun interface Orchestrate<T : Any, V : Any> : TypeReified<T> {
 
+    /**
+     * Takes a request and responds with the result of orchestration.
+     *
+     * The result of orchestration is passed to the subsequent orchestrate.
+     *
+     * @param T request type of Orchestrate
+     * @param V response type of Orchestrate
+     */
     fun orchestrate(request: T): V
-
+
+    /**
+     * If the request parameter includes generics such as List<Foo>, this function must be implemented.
+     *
+     * Generics prevent type inference, so this function relies on the return value of the reified function to decode and pass the request.
+     */
     override fun reified(): TypeReference<T>? = null
 }

src/main/kotlin/org/rooftop/netx/api/OrchestrateChain.kt

@@ -2,64 +2,146 @@ package org.rooftop.netx.api
 
 import reactor.core.publisher.Mono
 
+/**
+ * Used to create an Orchestrator.
+ *
+ * Each operation in the OrchestrateChain is not executed immediately but deferred until the Orchestrator saga is executed.
+ *
+ * For detailed usage, refer to the Example of Orchestrator.
+ *
+ * @see Orchestrator
+ * @param OriginReq The first request of Orchestrator
+ * @param T The request type of each Chain
+ * @param V The response type of each Chain
+ */
 interface OrchestrateChain<OriginReq : Any, T : Any, V : Any> {
 
+    /**
+     * Joins the saga with the operation.
+     *
+     * @param orchestrate Operation to be executed along with the join
+     * @param rollback Rollback function to be executed if an exception is thrown in the current orchestrate or sub-orchestrate.
+     * @param S Response passed as the request to the next orchestrate and rollback.
+     * @return OrchestrateChain
+     * @see Orchestrate
+     * @see Rollback
+     */
     fun <S : Any> join(
         orchestrate: Orchestrate<V, S>,
         rollback: Rollback<V, *>? = null,
     ): OrchestrateChain<OriginReq, V, S>
 
+    /**
+     * @see join
+     */
     fun <S : Any> joinReactive(
         orchestrate: Orchestrate<V, Mono<S>>,
         rollback: Rollback<V, Mono<*>>? = null,
     ): OrchestrateChain<OriginReq, V, S>
 
+    /**
+     * @param contextOrchestrate Allows using Context maintained in each Saga.
+     * @param contextRollback Allows using Context maintained in each Saga.
+     * @see join
+     * @see ContextOrchestrate
+     * @see ContextRollback
+     */
     fun <S : Any> joinWithContext(
         contextOrchestrate: ContextOrchestrate<V, S>,
         contextRollback: ContextRollback<V, *>? = null,
     ): OrchestrateChain<OriginReq, V, S>
 
+    /**
+     * @see joinReactiveWithContext
+     */
     fun <S : Any> joinReactiveWithContext(
         contextOrchestrate: ContextOrchestrate<V, Mono<S>>,
         contextRollback: ContextRollback<V, Mono<*>>? = null,
     ): OrchestrateChain<OriginReq, V, S>
 
+    /**
+     * Commits the saga with the operation.
+     *
+     * @param orchestrate Operation to be executed along with the commit.
+     * @param rollback Rollback function to be executed if an exception is thrown in the current orchestrate.
+     * @param S The final return value of Orchestrator.
+     * @return Orchestrator
+     * @see Orchestrate
+     * @see Rollback*
+     */
     fun <S : Any> commit(
         orchestrate: Orchestrate<V, S>,
         rollback: Rollback<V, *>? = null,
     ): Orchestrator<OriginReq, S>
 
+    /**
+     * @see commit
+     */
     fun <S : Any> commitReactive(
         orchestrate: Orchestrate<V, Mono<S>>,
         rollback: Rollback<V, Mono<*>>? = null,
     ): Orchestrator<OriginReq, S>
 
+    /**
+     * @param contextOrchestrate Allows using Context maintained in each Saga.
+     * @param contextRollback Allows using Context maintained in each Saga.
+     * @see commit
+     * @see contextOrchestrate
+     * @see contextRollback
+     */
     fun <S : Any> commitWithContext(
         contextOrchestrate: ContextOrchestrate<V, S>,
         contextRollback: ContextRollback<V, *>? = null,
     ): Orchestrator<OriginReq, S>
 
+    /**
+     * @see commitWithContext
+     */
     fun <S : Any> commitReactiveWithContext(
         contextOrchestrate: ContextOrchestrate<V, Mono<S>>,
         contextRollback: ContextRollback<V, Mono<*>>? = null,
     ): Orchestrator<OriginReq, S>
 
     interface Pre<T : Any> {
+
+        /**
+         * Starts the saga with the operation.
+         *
+         * @param orchestrate Operation to be executed along with the start.
+         * @param rollback Rollback function to be executed if an exception is thrown in the current orchestrate or sub-orchestrate.
+         * @param S Response passed as the request to the next orchestrate and rollback.
+         * @return OrchestrateChain
+         * @see Orchestrate
+         * @see Rollback
+         */
         fun <V : Any> start(
             orchestrate: Orchestrate<T, V>,
             rollback: Rollback<T, *>? = null,
         ): OrchestrateChain<T, T, V>
 
+        /**
+         * @see start
+         */
         fun <V : Any> startReactive(
             orchestrate: Orchestrate<T, Mono<V>>,
             rollback: Rollback<T, Mono<*>>? = null,
         ): OrchestrateChain<T, T, V>
 
+        /**
+         * @param contextOrchestrate Allows using Context maintained in each Saga.
+         * @param contextRollback Allows using Context maintained in each Saga.
+         * @see start
+         * @see ContextOrchestrate
+         * @see ContextRollback
+         */
         fun <V : Any> startWithContext(
             contextOrchestrate: ContextOrchestrate<T, V>,
             contextRollback: ContextRollback<T, *>? = null,
         ): OrchestrateChain<T, T, V>
 
+        /**
+         * @see startWithContext
+         */
         fun <V : Any> startReactiveWithContext(
             contextOrchestrate: ContextOrchestrate<T, Mono<V>>,
             contextRollback: ContextRollback<T, Mono<*>>? = null,