Add Dokka docs

build-logic/build.gradle.kts

@@ -19,6 +19,7 @@ plugins {
 
 dependencies {
     implementation(libs.gradle.android)
+    implementation(libs.gradle.dokka)
     implementation(libs.gradle.kmp.configuration)
     implementation(libs.gradle.kotlin)
     implementation(libs.gradle.publish.maven)

build-logic/src/main/kotlin/dokka.gradle.kts

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2024 Matthew Nelson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+import org.jetbrains.dokka.DokkaConfiguration.Visibility
+import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import java.net.URL
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+tasks.withType<DokkaTaskPartial>().configureEach {
+    suppressInheritedMembers = true
+
+    dokkaSourceSets.configureEach {
+        includes.from("README.md")
+        noStdlibLink = true
+    }
+
+    dokkaSourceSets.configureEach {
+        sourceLink {
+            localDirectory = rootDir
+            remoteUrl = URL("https://github.com/05nelsonm/kmp-tor/tree/master")
+            remoteLineSuffix = "#L"
+        }
+    }
+
+    dokkaSourceSets.configureEach {
+        documentedVisibilities.set(setOf(
+            Visibility.PUBLIC,
+            Visibility.PROTECTED,
+        ))
+    }
+}

build.gradle.kts

@@ -21,6 +21,7 @@ plugins {
     alias(libs.plugins.android.app) apply(false)
     alias(libs.plugins.android.library) apply(false)
     alias(libs.plugins.binary.compat)
+    alias(libs.plugins.dokka)
 }
 
 allprojects {

gradle/libs.versions.toml

@@ -7,6 +7,7 @@ encoding = "2.2.1"
 
 gradle-android = "8.2.2"
 gradle-binary-compat = "0.14.0"
+gradle-dokka = "1.9.20"
 gradle-kmp-configuration = "0.2.2"
 gradle-kotlin = "1.9.24"
 gradle-publish-maven = "0.28.0"
@@ -31,6 +32,7 @@ encoding-base32 = { module = "io.matthewnelson.encoding:base32", version.ref = "
 encoding-base64 = { module = "io.matthewnelson.encoding:base64", version.ref = "encoding" }
 
 gradle-android = { module = "com.android.tools.build:gradle", version.ref = "gradle-android" }
+gradle-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradle-dokka" }
 gradle-kmp-configuration = { module = "io.matthewnelson:gradle-kmp-configuration-plugin", version.ref = "gradle-kmp-configuration" }
 gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradle-kotlin" }
 gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" }
@@ -54,4 +56,5 @@ ktor-network = { module = "io.ktor:ktor-network", version.ref = "ktor" }
 android-app = { id = "com.android.application", version.ref = "gradle-android" }
 android-library = { id = "com.android.library", version.ref = "gradle-android" }
 binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" }
+dokka = { id = "org.jetbrains.dokka", version.ref = "gradle-dokka" }
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" }

library/runtime-core/README.md

@@ -0,0 +1,5 @@
+# Module runtime-core
+
+Core primitives for kmp-tor operation, serving as the foundation 
+of other higher level dependencies such as `runtime-ctrl` and 
+`runtime`.

library/runtime-core/api/runtime-core.api

@@ -129,8 +129,8 @@ public final class io/matthewnelson/kmp/tor/runtime/core/EnqueuedJob$State : jav
 public abstract class io/matthewnelson/kmp/tor/runtime/core/Event {
 	public final field name Ljava/lang/String;
 	protected fun <init> (Ljava/lang/String;)V
+	protected abstract fun createProtected (Lio/matthewnelson/kmp/tor/runtime/core/Event;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
 	public final fun equals (Ljava/lang/Object;)Z
-	protected abstract fun factory (Lio/matthewnelson/kmp/tor/runtime/core/Event;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
 	public final fun hashCode ()I
 	public final fun observer (Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
 	public final fun observer (Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
@@ -2985,9 +2985,9 @@ public final class io/matthewnelson/kmp/tor/runtime/core/TorConfig$__TransPort$C
 public abstract class io/matthewnelson/kmp/tor/runtime/core/TorEvent : io/matthewnelson/kmp/tor/runtime/core/Event {
 	public static final field Companion Lio/matthewnelson/kmp/tor/runtime/core/TorEvent$Companion;
 	public synthetic fun <init> (Ljava/lang/String;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun createProtected (Lio/matthewnelson/kmp/tor/runtime/core/Event;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
+	protected final fun createProtected (Lio/matthewnelson/kmp/tor/runtime/core/TorEvent;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/TorEvent$Observer;
 	public static fun entries ()Ljava/util/Set;
-	public synthetic fun factory (Lio/matthewnelson/kmp/tor/runtime/core/Event;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/Event$Observer;
-	protected final fun factory (Lio/matthewnelson/kmp/tor/runtime/core/TorEvent;Ljava/lang/String;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent$Executor;Lio/matthewnelson/kmp/tor/runtime/core/OnEvent;)Lio/matthewnelson/kmp/tor/runtime/core/TorEvent$Observer;
 	public static fun valueOf (Ljava/lang/String;)Lio/matthewnelson/kmp/tor/runtime/core/TorEvent;
 	public static fun valueOfOrNull (Ljava/lang/String;)Lio/matthewnelson/kmp/tor/runtime/core/TorEvent;
 }
@@ -4069,8 +4069,8 @@ public final class io/matthewnelson/kmp/tor/runtime/core/util/IPAddressUtil {
 }
 
 public final class io/matthewnelson/kmp/tor/runtime/core/util/PortUtil {
-	public static final fun findAvailableAsync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;ILio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
-	public static final fun findAvailableSync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;ILio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;)Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;
+	public static final fun findNextAvailableAsync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;ILio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun findNextAvailableSync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;ILio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;)Lio/matthewnelson/kmp/tor/runtime/core/address/Port$Ephemeral;
 	public static final fun isAvailableAsync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port;Lio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final fun isAvailableSync (Lio/matthewnelson/kmp/tor/runtime/core/address/Port;Lio/matthewnelson/kmp/tor/runtime/core/address/LocalHost;)Z
 }

library/runtime-core/build.gradle.kts

@@ -33,6 +33,8 @@ kmpConfiguration {
         }
 
         common {
+            pluginIds("dokka")
+
             sourceSetMain {
                 dependencies {
                     implementation(libs.encoding.base16)

library/runtime-core/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/core/Callbacks.kt

@@ -37,6 +37,8 @@ import kotlin.jvm.JvmStatic
  * treated as an [UncaughtException] and dispatched
  * to [io.matthewnelson.kmp.tor.runtime.RuntimeEvent.ERROR]
  * observers.
+ *
+ * @see [noOp]
  * */
 public fun interface OnSuccess<in T: Any?>: ItBlock<T> {
 
@@ -65,6 +67,8 @@ public fun interface OnSuccess<in T: Any?>: ItBlock<T> {
  * treated as an [UncaughtException] and dispatched
  * to [io.matthewnelson.kmp.tor.runtime.RuntimeEvent.ERROR]
  * observers.
+ *
+ * @see [noOp]
  * */
 public fun interface OnFailure: ItBlock<Throwable> {
 
@@ -93,8 +97,8 @@ public fun interface OnFailure: ItBlock<Throwable> {
  * exceptions will be treated as an [UncaughtException] and dispatched
  * to [io.matthewnelson.kmp.tor.runtime.RuntimeEvent.ERROR].
  *
- * @see [OnEvent.noOp]
- * @see [OnEvent.Executor]
+ * @see [noOp]
+ * @see [Executor]
  * */
 public fun interface OnEvent<in Data: Any?>: ItBlock<Data> {
 
@@ -185,6 +189,7 @@ public fun interface OnEvent<in Data: Any?>: ItBlock<Data> {
                 }
             }
 
+            /** @suppress */
             public override fun toString(): String = "OnEvent.Executor.Main"
         }
 
@@ -203,6 +208,7 @@ public fun interface OnEvent<in Data: Any?>: ItBlock<Data> {
 
             @InternalKmpTorApi
             public override fun execute(handler: CoroutineContext, executable: Executable) { executable.execute() }
+            /** @suppress */
             public override fun toString(): String = "OnEvent.Executor.Immediate"
         }
     }
@@ -299,6 +305,7 @@ public fun interface Disposable {
             }
         }
 
+        /** @suppress */
         public override fun toString(): String = "Disposable.Once@${hashCode()}"
     }
 
@@ -393,6 +400,7 @@ public fun interface Executable {
             }
         }
 
+        /** @suppress */
         public override fun toString(): String = "Executable.Once@${hashCode()}"
     }
 

library/runtime-core/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/core/EnqueuedJob.kt

@@ -38,8 +38,16 @@ import kotlin.jvm.*
  * discarded.
  *
  * Heavily inspired by [kotlinx.coroutines.Job]
+ *
+ * @see [toImmediateErrorJob]
+ * @see [toImmediateSuccessJob]
  * */
 public abstract class EnqueuedJob protected constructor(
+
+    /**
+     * The name for this job. Will be utilized with error handling
+     * for contextual purposes.
+     * */
     @JvmField
     public val name: String,
     onFailure: OnFailure,
@@ -66,7 +74,7 @@ public abstract class EnqueuedJob protected constructor(
     /**
      * The [ExecutionPolicy] of this job.
      *
-     * @see [ExecutionPolicy]
+     * Default: [ExecutionPolicy.DEFAULT]
      * */
     public open val executionPolicy: ExecutionPolicy = ExecutionPolicy.DEFAULT
 
@@ -101,8 +109,8 @@ public abstract class EnqueuedJob protected constructor(
     /**
      * Checks if the job is in a completion state or not.
      *
-     * @return true when [state] is [Enqueued] or [Executing]
-     *   otherwise false
+     * @return true when [state] is [Enqueued] or [Executing],
+     *   otherwise false.
      * */
     @get:JvmName("isActive")
     public val isActive: Boolean get() = when (_state) {
@@ -114,7 +122,7 @@ public abstract class EnqueuedJob protected constructor(
     }
 
     /**
-     * The current [State] of the job
+     * The current [State] of the job.
      * */
     @get:JvmName("state")
     public val state: State get() = _state
@@ -279,6 +287,11 @@ public abstract class EnqueuedJob protected constructor(
      * @see [Cancellation]
      * */
     public class ExecutionPolicy private constructor(
+
+        /**
+         * The [Cancellation] configuration of a job while it is
+         * in a state of [State.Executing].
+         * */
         @JvmField
         public val cancellation: Cancellation,
     ) {
@@ -435,8 +448,11 @@ public abstract class EnqueuedJob protected constructor(
                 }
             }
 
+            /** @suppress */
             public override fun equals(other: Any?): Boolean = privateEquals(other)
+            /** @suppress */
             public override fun hashCode(): Int = privateHashCode()
+            /** @suppress */
             public override fun toString(): String = privateToString()
         }
 
@@ -471,13 +487,17 @@ public abstract class EnqueuedJob protected constructor(
             }
 
             internal companion object {
+
                 @JvmSynthetic
                 internal fun get(): Builder = Builder()
             }
         }
 
+        /** @suppress */
         public override fun equals(other: Any?): Boolean = privateEquals(other)
+        /** @suppress */
         public override fun hashCode(): Int = privateHashCode()
+        /** @suppress */
         public override fun toString(): String = privateToString()
     }
 
@@ -711,6 +731,7 @@ public abstract class EnqueuedJob protected constructor(
         }
     }
 
+    /** @suppress */
     public final override fun toString(): String = toString(_state)
 
     private fun toString(state: State): String {
@@ -727,6 +748,7 @@ public abstract class EnqueuedJob protected constructor(
      * @see [io.matthewnelson.kmp.tor.runtime.core.ctrl.TorCmd.Unprivileged.Processor]
      * @see [io.matthewnelson.kmp.tor.runtime.core.util.awaitAsync]
      * @see [io.matthewnelson.kmp.tor.runtime.core.util.awaitSync]
+     * @suppress
      * */
     @InternalKmpTorApi
     public interface Argument

library/runtime-core/src/commonMain/kotlin/io/matthewnelson/kmp/tor/runtime/core/Event.kt

@@ -72,7 +72,7 @@ import kotlin.jvm.JvmField
  *                 }
  *         }
  *
- *         protected final override fun factory(
+ *         protected final override fun createProtected(
  *             event: MyEvent,
  *             tag: String?,
  *             executor: OnEvent.Executor?,
@@ -169,24 +169,9 @@ public abstract class Event<Data: Any?, E: Event<Data, E, O>, O: Event.Observer<
         onEvent: OnEvent<Data>,
     ): O {
         @Suppress("UNCHECKED_CAST")
-        return factory(this as E, tag, executor, onEvent)
+        return createProtected(this as E, tag, executor, onEvent)
     }
 
-    public final override fun equals(other: Any?): Boolean {
-        if (other !is Event<*, *, *>) return false
-        if (other::class != this::class) return false
-        return other.name == name
-    }
-
-    public final override fun hashCode(): Int {
-        var result = 17
-        result = result * 31 + this::class.hashCode()
-        result = result * 31 + name.hashCode()
-        return result
-    }
-
-    public final override fun toString(): String = name
-
     /**
      * Base abstraction for creating event observer types.
      *
@@ -264,8 +249,6 @@ public abstract class Event<Data: Any?, E: Event<Data, E, O>, O: Event.Observer<
             }
         }
 
-        public final override fun toString(): String = toString(isStatic = false)
-
         /**
          * Helper for processor implementations as to not expose a
          * static tag externally.
@@ -291,18 +274,10 @@ public abstract class Event<Data: Any?, E: Event<Data, E, O>, O: Event.Observer<
             append("]@")
             append(hashCode())
         }
-    }
 
-    /**
-     * Protected factory function for creating instances
-     * of the [Event.Observer] implementation.
-     * */
-    protected abstract fun factory(
-        event: E,
-        tag: String?,
-        executor: OnEvent.Executor?,
-        onEvent: OnEvent<Data>,
-    ): O
+        /** @suppress */
+        public final override fun toString(): String = toString(isStatic = false)
+    }
 
     /**
      * Abstraction for the [Event] implementation's companion object.
@@ -341,4 +316,33 @@ public abstract class Event<Data: Any?, E: Event<Data, E, O>, O: Event.Observer<
          * */
         protected abstract val lazyEntries: ThisBlock<LinkedHashSet<E>>
     }
+
+    /**
+     * Protected factory function for creating instances of the
+     * [Event.Observer] implementation.
+     * */
+    protected abstract fun createProtected(
+        event: E,
+        tag: String?,
+        executor: OnEvent.Executor?,
+        onEvent: OnEvent<Data>,
+    ): O
+
+    /** @suppress */
+    public final override fun equals(other: Any?): Boolean {
+        if (other !is Event<*, *, *>) return false
+        if (other::class != this::class) return false
+        return other.name == name
+    }
+
+    /** @suppress */
+    public final override fun hashCode(): Int {
+        var result = 17
+        result = result * 31 + this::class.hashCode()
+        result = result * 31 + name.hashCode()
+        return result
+    }
+
+    /** @suppress */
+    public final override fun toString(): String = name
 }