removed unused imports, added detailed comments to EncodedFormat and PackedFormat

Author: rasros

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

@@ -1,54 +1,63 @@
 package com.eignex.kencode
 
-import PackedFormat
 import kotlinx.serialization.*
 import kotlinx.serialization.modules.SerializersModule
 
+/**
+ * Holds the configuration for an [EncodedFormat] instance.
+ *
+ * @property codec The ASCII-safe byte codec used to turn raw bytes into text (e.g., Base62, Base64).
+ * @property checksum An optional checksum appended to the binary payload and verified upon decoding.
+ * @property binaryFormat The underlying binary serialization format used before encoding to text.
+ */
 data class EncodedConfiguration(
     val codec: ByteEncoding = Base62,
     val checksum: Checksum? = null,
     val binaryFormat: BinaryFormat = PackedFormat.Default
 )
 
 /**
- * Text `StringFormat` that combines:
+ * Text `StringFormat` that produces short, predictable string tokens by composing:
  *
- * - A binary format (e.g. [PackedFormat], `ProtoBuf`)
- * - An optional checksum
- * - An ASCII-safe byte encoding (e.g. [Base62], [Base64], [Base36], [Base85])
+ * 1. A binary format (e.g. [PackedFormat], `ProtoBuf`).
+ * 2. An optional checksum.
+ * 3. An ASCII-safe byte encoding (e.g. [Base62], [Base64], [Base36], [Base85]).
  *
  * Typical use:
+ * - `encodeToString`: serialize -> (optionally) append checksum -> encode bytes to text.
+ * - `decodeFromString`: decode text to bytes -> (optionally) verify checksum -> deserialize.
  *
- * - `encodeToString`: serialize → (optionally) append checksum → encode bytes
- * - `decodeFromString`: decode bytes → (optionally) verify checksum → deserialize
+ * Use the [EncodedFormat] builder function to create a customized instance.
  *
- * This is intended for short, predictable tokens for URLs, headers, file names, etc.
- *
- * @property codec ASCII-safe byte codec used to turn raw bytes into text.
- * @property checksum Optional checksum appended to the binary payload and verified on decode.
- * @property binaryFormat Binary serialization format used before encoding.
+ * @property configuration The active configuration dictating the codec, checksum, and binary format.
  */
 @OptIn(ExperimentalSerializationApi::class)
 open class EncodedFormat(
     val configuration: EncodedConfiguration,
 ) : StringFormat {
 
+    /**
+     * Secondary constructor for direct instantiation without the builder.
+     */
     constructor(
         codec: ByteEncoding = Base62,
         checksum: Checksum? = null,
         binaryFormat: BinaryFormat = PackedFormat,
     ) : this(EncodedConfiguration(codec, checksum, binaryFormat))
 
+    /**
+     * Delegates to the underlying [BinaryFormat]'s serializers module.
+     */
     override val serializersModule: SerializersModule get() = configuration.binaryFormat.serializersModule
 
     /**
-     * Default format: `PackedFormat` + `Base62` without checksum.
+     * Default format: `PackedFormat` + `Base62` without a checksum.
      */
     companion object Default : EncodedFormat()
 
     /**
-     * Serializes [value] with [binaryFormat], optionally appends [checksum],
-     * and encodes the result using [codec].
+     * Serializes [value] with the configured binary format, optionally appends a checksum,
+     * and encodes the resulting byte array using the text codec.
      */
     override fun <T> encodeToString(
         serializer: SerializationStrategy<T>, value: T
@@ -61,10 +70,10 @@ open class EncodedFormat(
     }
 
     /**
-     * Decodes [string] using [codec], optionally verifies [checksum],
-     * then deserializes the remaining bytes with [binaryFormat].
+     * Decodes [string] using the text codec, optionally verifies and strips the checksum,
+     * then deserializes the remaining bytes with the configured binary format.
      *
-     * @throws IllegalArgumentException if a checksum is configured and does not match.
+     * @throws IllegalArgumentException if a checksum is configured and the verification fails.
      */
     override fun <T> decodeFromString(
         deserializer: DeserializationStrategy<T>, string: String
@@ -85,12 +94,39 @@ open class EncodedFormat(
     }
 }
 
+/**
+ * Builder for configuring [EncodedFormat] instances.
+ */
 class EncodedFormatBuilder {
+    /**
+     * The ASCII-safe byte codec used to turn raw bytes into text. Defaults to [Base62].
+     */
     var codec: ByteEncoding = Base62
+
+    /**
+     * An optional checksum appended to the binary payload. Defaults to `null`.
+     */
     var checksum: Checksum? = null
+
+    /**
+     * The underlying binary serialization format. Defaults to [PackedFormat.Default].
+     */
     var binaryFormat: BinaryFormat = PackedFormat.Default
 }
 
+/**
+ * Creates a customized [EncodedFormat] instance.
+ *
+ * ```
+ * val format = EncodedFormat {
+ * codec = Base36
+ * checksum = Crc16
+ * }
+ * ```
+ *
+ * @param from An existing [EncodedFormat] instance to copy defaults from.
+ * @param builderAction The configuration block.
+ */
 fun EncodedFormat(
     from: EncodedFormat = EncodedFormat.Default,
     builderAction: EncodedFormatBuilder.() -> Unit

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

@@ -1,6 +1,5 @@
 package com.eignex.kencode
 
-import PackedConfiguration
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.descriptors.*

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

@@ -1,6 +1,5 @@
 package com.eignex.kencode
 
-import PackedConfiguration
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerializationStrategy
 import kotlinx.serialization.descriptors.*

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

@@ -1,10 +1,16 @@
-import com.eignex.kencode.PackedDecoder
-import com.eignex.kencode.PackedEncoder
+package com.eignex.kencode
+
 import kotlinx.serialization.*
 import kotlinx.serialization.modules.EmptySerializersModule
 import kotlinx.serialization.modules.SerializersModule
 import java.io.ByteArrayOutputStream
 
+/**
+ * Holds the configuration for a [PackedFormat] instance.
+ *
+ * @property defaultVarInt When true, all `Int` and `Long` fields without specific annotations are encoded as variable-length integers.
+ * @property defaultZigZag When true, all `Int` and `Long` fields without specific annotations are ZigZag encoded to efficiently store small negative numbers.
+ */
 data class PackedConfiguration(
     val defaultVarInt: Boolean = false,
     val defaultZigZag: Boolean = false
@@ -14,26 +20,32 @@ data class PackedConfiguration(
  * Compact `BinaryFormat` optimized for small, flat Kotlin data classes.
  *
  * Features:
- * - Booleans and nullability encoded as bitmasks
- * - Optional varint / zig-zag via `@VarInt` / `@VarUInt` annotations
- * - Fixed, deterministic field order based on declaration
+ * - Booleans and nullability encoded as compact bitmasks in a class header.
+ * - Optional varint / zig-zag encoding via `@VarInt` / `@VarUInt` annotations, or globally via [PackedConfiguration].
+ * - Fixed, deterministic field order based on declaration.
  *
  * Limitations:
- * - No nested objects, collections, or maps
- * - No polymorphism
+ * - Nested objects and collections are supported, but do not share bitmasks across structural boundaries.
+ * - Polymorphism support is limited/unoptimized compared to full-featured formats.
+ *
+ * Use the [PackedFormat] builder function to create a customized instance.
  *
- * For richer models, use `ProtoBuf` (or another [BinaryFormat]) with [com.eignex.kencode.EncodedFormat].
+ * @property configuration The active configuration for default varint/zigzag behaviors.
+ * @property serializersModule The module used to resolve contextual and polymorphic serializers.
  */
 @OptIn(ExperimentalSerializationApi::class)
 open class PackedFormat(
     val configuration: PackedConfiguration = PackedConfiguration(),
     override val serializersModule: SerializersModule = EmptySerializersModule()
 ) : BinaryFormat {
 
+    /**
+     * Default instance with no default varint/zigzag optimizations applied automatically.
+     */
     companion object Default : PackedFormat()
 
     /**
-     * Encodes [value] into a compact binary representation using [PackedEncoder].
+     * Encodes [value] into a compact binary representation.
      */
     override fun <T> encodeToByteArray(
         serializer: SerializationStrategy<T>, value: T
@@ -45,7 +57,7 @@ open class PackedFormat(
     }
 
     /**
-     * Decodes [bytes] produced by [PackedFormat] using [PackedDecoder].
+     * Decodes [bytes] produced by [PackedFormat] back into an object of type [T].
      */
     override fun <T> decodeFromByteArray(
         deserializer: DeserializationStrategy<T>, bytes: ByteArray
@@ -55,13 +67,40 @@ open class PackedFormat(
     }
 }
 
-
+/**
+ * Builder for configuring [PackedFormat] instances.
+ */
 class PackedFormatBuilder {
+    /**
+     * The module containing contextual and polymorphic serializers.
+     */
     var serializersModule: SerializersModule = EmptySerializersModule()
+
+    /**
+     * If true, applies variable-length integer encoding to all `Int` and `Long` fields by default.
+     */
     var defaultVarInt: Boolean = false
+
+    /**
+     * If true, applies ZigZag encoding to all `Int` and `Long` fields by default.
+     * Overrides [defaultVarInt] as ZigZag inherently implies variable-length encoding.
+     */
     var defaultZigZag: Boolean = false
 }
 
+/**
+ * Creates a customized [PackedFormat] instance.
+ *
+ * ```
+ * val format = PackedFormat {
+ * defaultZigZag = true
+ * serializersModule = myCustomModule
+ * }
+ * ```
+ *
+ * @param from An existing [PackedFormat] instance to copy defaults from.
+ * @param builderAction The configuration block.
+ */
 fun PackedFormat(
     from: PackedFormat = PackedFormat.Default,
     builderAction: PackedFormatBuilder.() -> Unit

src/test/kotlin/com/eignex/kencode/Examples.kt

@@ -1,6 +1,5 @@
 package com.eignex.kencode
 
-import PackedFormat
 import kotlinx.serialization.*
 import kotlinx.serialization.protobuf.ProtoBuf
 import org.bouncycastle.jce.provider.BouncyCastleProvider

src/test/kotlin/com/eignex/kencode/PackedFormatTest.kt

@@ -2,7 +2,6 @@
 
 package com.eignex.kencode
 
-import PackedFormat
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.builtins.nullable
 import kotlinx.serialization.builtins.serializer