Add KDoc to public API across all modules (KOJAK-36) (#10)

## Summary

- Add KDoc documentation to all 15 undocumented public Kotlin files
across 5 modules (core, http, kafka, postgres, mysql)
- Follow existing project KDoc style: concise, `[ClassName]` references,
no `@param`/`@return`
- Documentation-only changes — zero code modifications, 80 lines added

## Modules covered

| Module | Files | What was documented |
|--------|-------|---------------------|
| okapi-core | 6 | Data classes, enums, sealed interface
(`OutboxMessage`, `OutboxId`, `OutboxStatus`, `OutboxEntry`,
`DeliveryResult`, `RetryPolicy`) |
| okapi-http | 4 | Transport impl, delivery info, DSL builder with usage
example, enum |
| okapi-kafka | 3 | Transport impl, delivery info, DSL builder with
usage example |
| okapi-postgres | 1 | Store implementation class |
| okapi-mysql | 1 | Store implementation class |

## Test plan

- [x] `./gradlew ktlintCheck` — passed
- [x] `./gradlew compileKotlin` — passed (verifies KDoc `[references]`
don't break compilation)
- [x] No code changes — only KDoc comment additions

Author: endrju19

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/DeliveryResult.kt

@@ -1,5 +1,11 @@
 package com.softwaremill.okapi.core
 
+/**
+ * Outcome of a single delivery attempt by a [MessageDeliverer].
+ *
+ * [OutboxEntryProcessor] uses this to decide whether to retry, mark as failed,
+ * or mark as delivered.
+ */
 sealed interface DeliveryResult {
     data object Success : DeliveryResult
 

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/OutboxEntry.kt

@@ -2,6 +2,12 @@ package com.softwaremill.okapi.core
 
 import java.time.Instant
 
+/**
+ * Persistent representation of an outbox message with delivery state.
+ *
+ * Created via [createPending] and progressed through [retry], [toDelivered],
+ * or [toFailed] — each returning a new immutable copy.
+ */
 data class OutboxEntry(
     val outboxId: OutboxId,
     val messageType: String,
@@ -15,6 +21,7 @@ data class OutboxEntry(
     val lastError: String?,
     val deliveryMetadata: String,
 ) {
+    /** Returns a copy scheduled for another delivery attempt. */
     fun retry(now: Instant, lastError: String): OutboxEntry = copy(
         status = OutboxStatus.PENDING,
         updatedAt = now,
@@ -23,20 +30,23 @@ data class OutboxEntry(
         lastError = lastError,
     )
 
+    /** Returns a copy marked as permanently failed. */
     fun toFailed(now: Instant, lastError: String): OutboxEntry = copy(
         status = OutboxStatus.FAILED,
         updatedAt = now,
         lastAttempt = now,
         lastError = lastError,
     )
 
+    /** Returns a copy marked as successfully delivered. */
     fun toDelivered(now: Instant): OutboxEntry = copy(
         status = OutboxStatus.DELIVERED,
         updatedAt = now,
         lastAttempt = now,
     )
 
     companion object {
+        /** Creates a new PENDING entry from a [message] and [deliveryInfo]. */
         fun createPending(message: OutboxMessage, deliveryInfo: DeliveryInfo, now: Instant): OutboxEntry =
             createPending(message, deliveryType = deliveryInfo.type, deliveryMetadata = deliveryInfo.serialize(), now = now)
 

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/OutboxId.kt

@@ -2,9 +2,11 @@ package com.softwaremill.okapi.core
 
 import java.util.UUID
 
+/** Unique identifier for an outbox entry. Wraps a [UUID] for type safety. */
 @JvmInline
 value class OutboxId(val raw: UUID) {
     companion object {
+        /** Generates a new random identifier. */
         fun new(): OutboxId = OutboxId(UUID.randomUUID())
     }
 }

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/OutboxMessage.kt

@@ -1,5 +1,6 @@
 package com.softwaremill.okapi.core
 
+/** Business message to be delivered via the transactional outbox. */
 data class OutboxMessage(
     val messageType: String,
     val payload: String,

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/OutboxStatus.kt

@@ -1,12 +1,14 @@
 package com.softwaremill.okapi.core
 
+/** Lifecycle status of an [OutboxEntry]. */
 enum class OutboxStatus {
     PENDING,
     DELIVERED,
     FAILED,
     ;
 
     companion object {
+        /** Resolves a status by matching the given [value] against enum entry names. Throws if unknown. */
         fun from(value: String): OutboxStatus = requireNotNull(entries.find { it.name == value }) {
             "Unknown outbox status: $value"
         }

okapi-core/src/main/kotlin/com/softwaremill/okapi/core/RetryPolicy.kt

@@ -1,9 +1,11 @@
 package com.softwaremill.okapi.core
 
+/** Determines how many retries are allowed after the initial delivery attempt before an entry is marked as [OutboxStatus.FAILED]. */
 data class RetryPolicy(val maxRetries: Int) {
     init {
         require(maxRetries >= 0) { "maxRetries must be >= 0, got: $maxRetries" }
     }
 
+    /** Returns `true` if [currentRetries] has not yet reached [maxRetries]. */
     fun shouldRetry(currentRetries: Int): Boolean = currentRetries < maxRetries
 }

okapi-http/src/main/kotlin/com/softwaremill/okapi/http/HttpDeliveryInfo.kt

@@ -4,6 +4,12 @@ import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import com.fasterxml.jackson.module.kotlin.readValue
 import com.softwaremill.okapi.core.DeliveryInfo
 
+/**
+ * Delivery metadata for HTTP webhook transport.
+ *
+ * [serviceName] is resolved to a base URL via [ServiceUrlResolver] at delivery time.
+ * [endpointPath] is appended to form the full URL.
+ */
 data class HttpDeliveryInfo(
     override val type: String = TYPE,
     val serviceName: String,
@@ -22,6 +28,7 @@ data class HttpDeliveryInfo(
         const val TYPE = "http"
         private val mapper = jacksonObjectMapper()
 
+        /** Deserializes from JSON stored in [OutboxEntry.deliveryMetadata]. */
         fun deserialize(json: String): HttpDeliveryInfo = mapper.readValue(json)
     }
 }

okapi-http/src/main/kotlin/com/softwaremill/okapi/http/HttpDeliveryInfoBuilder.kt

@@ -22,4 +22,16 @@ class HttpDeliveryInfoBuilder {
     )
 }
 
+/**
+ * DSL for building [HttpDeliveryInfo].
+ *
+ * ```
+ * val info = httpDeliveryInfo {
+ *     serviceName = "order-service"
+ *     endpointPath = "/api/events"
+ *     httpMethod = HttpMethod.POST
+ *     header("X-Correlation-Id", correlationId)
+ * }
+ * ```
+ */
 fun httpDeliveryInfo(block: HttpDeliveryInfoBuilder.() -> Unit): HttpDeliveryInfo = HttpDeliveryInfoBuilder().apply(block).build()

okapi-http/src/main/kotlin/com/softwaremill/okapi/http/HttpMessageDeliverer.kt

@@ -9,6 +9,16 @@ import java.net.http.HttpRequest
 import java.net.http.HttpResponse
 import java.time.Duration
 
+/**
+ * [MessageDeliverer] that sends outbox entries as HTTP requests via JDK [HttpClient].
+ *
+ * Status code classification:
+ * - 2xx → [DeliveryResult.Success]
+ * - 5xx, 429, 408 → [DeliveryResult.RetriableFailure] (configurable via [retriableStatusCodes])
+ * - other → [DeliveryResult.PermanentFailure]
+ *
+ * Connection errors are treated as retriable.
+ */
 class HttpMessageDeliverer(
     private val urlResolver: ServiceUrlResolver,
     private val httpClient: HttpClient = defaultHttpClient(),

okapi-http/src/main/kotlin/com/softwaremill/okapi/http/HttpMethod.kt

@@ -1,5 +1,6 @@
 package com.softwaremill.okapi.http
 
+/** HTTP methods supported by [HttpMessageDeliverer]. */
 enum class HttpMethod {
     POST,
     PUT,