add kdoc

Author: rasros

src/main/kotlin/com/eignex/kencode/Annotations.kt

@@ -5,11 +5,58 @@ package com.eignex.kencode
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialInfo
 
+/**
+ * Marks an `Int` or `Long` property to be encoded using **signed varint** encoding.
+ *
+ * Behavior:
+ * - Values are ZigZag–transformed, so small negative numbers encode compactly.
+ * - Serialized using a variable-length LEB128-style varint.
+ * - Applies only to `Int` and `Long` fields inside `PackedFormat` structures.
+ *
+ * Decoding:
+ * - Automatically applies ZigZag decode.
+ *
+ * Usage:
+ * ```
+ * @Serializable
+ * data class Example(
+ *     @VarInt val delta: Int,   // small negatives become very compact
+ *     @VarInt val offset: Long
+ * )
+ * ```
+ *
+ * Has no effect for primitive types outside `PackedFormat`.
+ */
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class VarInt
 
+/**
+ * Marks an `Int` or `Long` property to be encoded using **unsigned varint** encoding.
+ *
+ * Behavior:
+ * - No ZigZag transform; values are treated as non-negative.
+ * - Serialized using a variable-length LEB128-style varint.
+ * - Applies only to `Int` and `Long` fields inside `PackedFormat` structures.
+ *
+ * Recommended for:
+ * - IDs
+ * - version counters
+ * - monotonic sequence numbers
+ * - any value that is always `>= 0`
+ *
+ * Usage:
+ * ```
+ * @Serializable
+ * data class Example(
+ *     @VarUInt val id: Long,    // compact for small and medium positive values
+ *     @VarUInt val count: Int
+ * )
+ * ```
+ *
+ * Has no effect for primitive types outside `PackedFormat`.
+ */
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY)
 @Retention(AnnotationRetention.RUNTIME)

src/main/kotlin/com/eignex/kencode/BaseRadix.kt

@@ -87,8 +87,8 @@ open class BaseRadix(
         val bytesCount = blockIndex + 1
         ceil((bytesCount * 8) / logBase).toInt()
     }.also { arr ->
-        // Ensure strictly increasing encoded length for each additional input byte,
-        // to avoid ambiguity when decoding.
+        // Ensure strictly increasing encoded length for each additional input
+        // byte, // to avoid ambiguity when decoding.
         for (i in 1 until arr.size) {
             val prev = arr[i - 1]
             while (arr[i] <= prev) {

src/main/kotlin/com/eignex/kencode/ByteEncoding.kt

@@ -1,15 +1,43 @@
 package com.eignex.kencode
 
 /**
- * Abstraction for byte→string and string→byte encoders.
+ * Abstraction for bidirectional byte–text encodings.
+ *
+ * A `ByteEncoding` converts raw binary data into an ASCII-safe string
+ * representation, and back. Implementations include:
+ *
+ * - `Base36` / `Base62` (`BaseRadix`-based)
+ * - `Base64` / `Base64UrlSafe`
+ * - `Base85`
+ *
+ * Contract:
+ * - `encode` must produce a deterministic, reversible representation.
+ * - `decode` must reject invalid input via `IllegalArgumentException`.
+ * - All implementations are pure and thread-safe.
+ *
+ * Usage:
+ * ```
+ * val encoded = Base62.encode(bytes)
+ * val decoded = Base62.decode(encoded)
+ * ```
  */
 interface ByteEncoding {
 
+    /**
+     * Encode the given byte range `[offset, offset + length)` into a text
+     * representation. Throws [IllegalArgumentException] on invalid offset or
+     * length.
+     */
     fun encode(
         input: ByteArray,
         offset: Int = 0,
         length: Int = input.size - offset
     ): String
 
+    /**
+     * Decode an encoded string back into the original bytes. Throws
+     * [IllegalArgumentException] the input contains characters not in the
+     * encoding alphabet or the input is structurally invalid for the encoding.
+     */
     fun decode(input: CharSequence): ByteArray
 }