Add more kdoc

Author: rossdanderson

util/api/datasourcex-util.api

@@ -191,6 +191,11 @@ public final class com/caplin/integration/datasourcex/util/flow/FlowMapKt {
 public abstract interface class com/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent {
 }
 
+public final class com/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent$Cleared : com/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent {
+	public static final field INSTANCE Lcom/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent$Cleared;
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class com/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent$EventUpdate : com/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent {
 	public static final synthetic fun box-impl (Lcom/caplin/integration/datasourcex/util/flow/MapEvent$EntryEvent;)Lcom/caplin/integration/datasourcex/util/flow/FlowMapStreamEvent$EventUpdate;
 	public static fun constructor-impl (Lcom/caplin/integration/datasourcex/util/flow/MapEvent$EntryEvent;)Lcom/caplin/integration/datasourcex/util/flow/MapEvent$EntryEvent;

util/src/main/kotlin/com/caplin/integration/datasourcex/util/AntPatternNamespace.kt

@@ -31,6 +31,13 @@ class AntPatternNamespace(pattern: String) : Namespace {
     }
   }
 
+  /**
+   * Represents a mapping between a from-pattern and a to-pattern, used for injecting user-specific
+   * information into subjects requested by Liberator.
+   *
+   * @property fromPattern The pattern used to match the incoming subject.
+   * @property toPattern The pattern used to map to the destination subject.
+   */
   class ObjectMap(val fromPattern: String, val toPattern: String) {
     operator fun component1(): String = fromPattern
 
@@ -59,12 +66,20 @@ class AntPatternNamespace(pattern: String) : Namespace {
     }
   }
 
+  /** The Ant-style path pattern used by this namespace. */
   val pattern = pattern.removeSuffix("/")
 
   private val matcher = AntRegexPathMatcher(pattern)
 
   override fun match(subject: String): Boolean = matcher.regex.matchEntire(subject) != null
 
+  /**
+   * Extracts path variables from a matching subject.
+   *
+   * @param subject The subject to extract variables from. Must match the [pattern].
+   * @return A map of path variable names to their extracted values.
+   * @throws IllegalStateException If the subject does not match the pattern.
+   */
   fun extractPathVariables(subject: String): Map<String, String> {
     val groups =
         checkNotNull(matcher.regex.matchEntire(subject)) {

util/src/main/kotlin/com/caplin/integration/datasourcex/util/KLogger.kt

@@ -10,45 +10,71 @@ import org.slf4j.LoggerFactory
 @JvmInline
 value class KLogger(private val logger: Logger) {
 
+  /** Logs an error message lazily evaluated from [message] if error logging is enabled. */
   fun error(message: () -> Any?) {
     if (logger.isErrorEnabled) logger.error(message().toString())
   }
 
+  /** Logs a warning message lazily evaluated from [message] if warn logging is enabled. */
   fun warn(message: () -> Any?) {
     if (logger.isWarnEnabled) logger.warn(message().toString())
   }
 
+  /** Logs an info message lazily evaluated from [message] if info logging is enabled. */
   fun info(message: () -> Any?) {
     if (logger.isInfoEnabled) logger.info(message().toString())
   }
 
+  /** Logs a debug message lazily evaluated from [message] if debug logging is enabled. */
   fun debug(message: () -> Any?) {
     if (logger.isDebugEnabled) logger.debug(message().toString())
   }
 
+  /** Logs a trace message lazily evaluated from [message] if trace logging is enabled. */
   fun trace(message: () -> Any?) {
     if (logger.isTraceEnabled) logger.trace(message().toString())
   }
 
+  /**
+   * Logs an error message with a [throwable], lazily evaluated from [message], if error logging is
+   * enabled.
+   */
   fun error(throwable: Throwable?, message: () -> Any?) {
     if (logger.isErrorEnabled) logger.error(message().toString(), throwable)
   }
 
+  /**
+   * Logs a warning message with a [throwable], lazily evaluated from [message], if warn logging is
+   * enabled.
+   */
   fun warn(throwable: Throwable?, message: () -> Any?) {
     if (logger.isWarnEnabled) logger.warn(message().toString(), throwable)
   }
 
+  /**
+   * Logs an info message with a [throwable], lazily evaluated from [message], if info logging is
+   * enabled.
+   */
   fun info(throwable: Throwable?, message: () -> Any?) {
     if (logger.isInfoEnabled) logger.info(message().toString(), throwable)
   }
 
+  /**
+   * Logs a debug message with a [throwable], lazily evaluated from [message], if debug logging is
+   * enabled.
+   */
   fun debug(throwable: Throwable?, message: () -> Any?) {
     if (logger.isDebugEnabled) logger.debug(message().toString(), throwable)
   }
 
+  /**
+   * Logs a trace message with a [throwable], lazily evaluated from [message], if trace logging is
+   * enabled.
+   */
   fun trace(throwable: Throwable?, message: () -> Any?) {
     if (logger.isTraceEnabled) logger.trace(message().toString(), throwable)
   }
 }
 
+/** Returns a [KLogger] instance for the specified class [T]. */
 inline fun <reified T : Any> getLogger(): KLogger = KLogger(LoggerFactory.getLogger(T::class.java))

util/src/main/kotlin/com/caplin/integration/datasourcex/util/ReadWriteLock.kt

@@ -11,8 +11,16 @@ class ReadWriteLock {
   private val readerMutex = Mutex()
   private val writerMutex = Mutex()
 
+  /**
+   * Executes the given [block] of code within a write lock. Suspends until the write lock can be
+   * acquired.
+   */
   suspend fun <R> withWriteLock(block: suspend () -> R): R = writerMutex.withLock(null) { block() }
 
+  /**
+   * Executes the given [block] of code within a read lock. Suspends until the read lock can be
+   * acquired.
+   */
   suspend fun <R> withReadLock(block: suspend () -> R): R =
       withContext(NonCancellable) {
         readLock()
@@ -23,6 +31,7 @@ class ReadWriteLock {
         }
       }
 
+  /** Acquires a read lock. Suspends if a write lock is currently held. */
   suspend fun readLock() =
       withContext(NonCancellable) {
         readerMutex.withLock {
@@ -31,6 +40,7 @@ class ReadWriteLock {
         }
       }
 
+  /** Releases a previously acquired read lock. */
   suspend fun readUnlock() =
       withContext(NonCancellable) {
         readerMutex.withLock {
@@ -39,7 +49,9 @@ class ReadWriteLock {
         }
       }
 
+  /** Acquires a write lock. Suspends if any read or write locks are currently held. */
   suspend fun writeLock() = writerMutex.lock()
 
+  /** Releases a previously acquired write lock. */
   fun writeUnlock() = writerMutex.unlock()
 }

util/src/main/kotlin/com/caplin/integration/datasourcex/util/SimpleDataSourceConfig.kt

@@ -3,14 +3,22 @@ package com.caplin.integration.datasourcex.util
 import java.nio.file.Path
 import java.util.UUID
 
+/** Configuration for creating a DataSource via [SimpleDataSourceFactory]. */
 sealed interface SimpleDataSourceConfig {
+  /** The directory where log files will be written. */
   val logDirectory: Path?
+  /** The name of the DataSource. */
   val name: String
+  /** The local label for the DataSource. */
   val localLabel: String
+  /** Any extra configuration to append to the configuration string. */
   val extraConfig: String?
 
+  /** Configuration for a DataSource that connects to a discovery service. */
   class Discovery(
+      /** The hostname of the discovery service. */
       val hostname: String,
+      /** The cluster name to join. */
       val clusterName: String = "caplin",
       override val name: String,
       override val logDirectory: Path?,
@@ -23,14 +31,19 @@ sealed interface SimpleDataSourceConfig {
     }
   }
 
+  /** Configuration for a DataSource that connects to specific peers. */
   class Peer(
       override val name: String,
       override val logDirectory: Path? = null,
       override val localLabel: String = "$name-${UUID.randomUUID()}",
       override val extraConfig: String? = null,
+      /** Optional configuration for accepting incoming connections. */
       val incoming: Incoming? = null,
+      /** List of outgoing peer connections. */
       val outgoing: List<Outgoing> = emptyList(),
+      /** List of services required before this DataSource becomes active. */
       val requiredServices: List<String> = emptyList(),
+      /** Whether to override development mode checks. */
       val devOverride: Boolean = false,
   ) : SimpleDataSourceConfig {
 
@@ -40,12 +53,14 @@ sealed interface SimpleDataSourceConfig {
       }
     }
 
+    /** Configuration for an outgoing peer connection. */
     class Outgoing(val hostname: String, val port: Int, val isWebsocket: Boolean) {
       override fun toString(): String {
         return "Outgoing(hostname='$hostname', port=$port, isWebsocket=$isWebsocket)"
       }
     }
 
+    /** Configuration for accepting incoming connections. */
     class Incoming(val port: Int, val isWebsocket: Boolean) {
       override fun toString(): String {
         return "Incoming(port=$port, isWebsocket=$isWebsocket)"

util/src/main/kotlin/com/caplin/integration/datasourcex/util/SimpleDataSourceFactory.kt

@@ -10,12 +10,20 @@ import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import java.nio.file.Files
 import java.util.logging.Logger
 
+/**
+ * A factory for creating [DataSource] instances from simplified configurations. Allows easy setup
+ * for tests and examples.
+ */
 object SimpleDataSourceFactory {
 
   private const val MAX_PATH_LENGTH = 32
 
   private val logger = getLogger<SimpleDataSourceFactory>()
 
+  /**
+   * The default [ObjectMapper] used for serializing and deserializing JSON payloads. It is
+   * pre-configured with the JavaTime module and DataSource serialization extensions.
+   */
   val defaultObjectMapper: ObjectMapper =
       jacksonObjectMapper()
           .configure(WRITE_DATES_AS_TIMESTAMPS, false)

util/src/main/kotlin/com/caplin/integration/datasourcex/util/flow/SetEvent.kt

@@ -15,19 +15,26 @@ import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onCompletion
 import kotlinx.coroutines.flow.onEach
 
+/** Events representing a mutation to a [Set]. */
 sealed interface SetEvent<out V : Any> {
 
+  /**
+   * Indicates that a consistent view of the set has been emitted and only updates will be seen from
+   * now on.
+   */
   object Populated : SetEvent<Nothing> {
     override fun toString(): String {
       return "Populated()"
     }
   }
 
+  /** Mutation event for a specific entry. */
   sealed interface EntryEvent<out V : Any> : SetEvent<V> {
     val value: V
 
     operator fun component1(): V = value
 
+    /** An event indicating a value has been inserted into the set. */
     class Insert<out V : Any>(override val value: V) : EntryEvent<V> {
 
       override fun equals(other: Any?): Boolean {
@@ -48,6 +55,7 @@ sealed interface SetEvent<out V : Any> {
       }
     }
 
+    /** An event indicating a value has been removed from the set. */
     class Removed<out V : Any>(override val value: V) : EntryEvent<V> {
 
       override fun equals(other: Any?): Boolean {
@@ -148,11 +156,22 @@ fun <V : Any> Flow<SetEvent<V>>.runningFoldToSet(
   }
 }
 
+/**
+ * Transforms a flow of sets into a merged flow by applying [entryEventTransformer] to each entry
+ * event (insert or remove). When a value is inserted, a new flow is created and merged. When a
+ * value is removed, the corresponding flow is cancelled.
+ */
 @JvmName("flatMapLatestAndMergeSet")
 fun <V : Any, R> Flow<Set<V>>.flatMapLatestAndMerge(
     entryEventTransformer: (EntryEvent<V>) -> Flow<R>
 ): Flow<R> = toEvents().flatMapLatestAndMerge(entryEventTransformer)
 
+/**
+ * Transforms a flow of [SetEvent] into a merged flow by applying [entryEventTransformer] to each
+ * entry event. When an [Insert] event is received, a new flow is created and its emissions are
+ * merged into the resulting flow. When a [Removed] event is received, the previously created flow
+ * for that value is cancelled.
+ */
 fun <V : Any, R> Flow<SetEvent<V>>.flatMapLatestAndMerge(
     entryEventTransformer: (EntryEvent<V>) -> Flow<R>
 ) = channelFlow {