Add dokka and a bit of javadoc

gradle/libs.versions.toml

@@ -38,6 +38,7 @@ kotest-multiplatform = { id = "io.kotest.multiplatform", version.ref = "kotest"
 kotlinx-benchmark = { id = "org.jetbrains.kotlinx.benchmark", version.ref = "kotlinx-benchmark" }
 mokkery = { id = "dev.mokkery", version = "1.9.24-1.7.0" }
 maven-central-publish = { id = "com.vanniktech.maven.publish", version = "0.28.0" }
+dokka = { id = "org.jetbrains.dokka", version = "1.9.20" }
 
 [bundles]
 logging-jvm = ["kotlin-logging-jvm", "slf4j-api", "logback-classic"]

kotlinx-serialization-smile-core/build.gradle.kts

@@ -1,11 +1,17 @@
 import com.vanniktech.maven.publish.SonatypeHost
 
 plugins {
+    // core kotlin plugins
     alias(libs.plugins.kotlin.multiplatform)
     alias(libs.plugins.kotlin.serialization)
+
+    // publish
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.maven.central.publish)
+
+    // test plugins
     alias(libs.plugins.kotest.multiplatform)
     alias(libs.plugins.mokkery)
-    alias(libs.plugins.maven.central.publish)
 }
 
 kotlin {

kotlinx-serialization-smile-core/src/commonMain/kotlin/io/github/vooft/kotlinsmile/Smile.kt

@@ -3,32 +3,28 @@ package io.github.vooft.kotlinsmile
 import io.github.vooft.kotlinsmile.adapter.SmileDecoderAdapter
 import io.github.vooft.kotlinsmile.adapter.SmileEncoderAdapter
 import kotlinx.serialization.DeserializationStrategy
-import kotlinx.serialization.KSerializer
 import kotlinx.serialization.SerializationStrategy
 import kotlinx.serialization.serializer
 
+/**
+ * Entry point for Smile encoding/decoding.
+ * The easiest way to start is to use companion object's methods that will use default configuration.
+ */
 open class Smile(private val config: SmileConfig) {
     fun <T> encode(serializer: SerializationStrategy<T>, value: T): ByteArray {
         val encoder = SmileEncoderAdapter(config)
         encoder.encodeSerializableValue(serializer, value)
         return encoder.toByteArray()
     }
 
-    fun <T> encode(objWithSerializer: ObjWithSerializer<T>) = encode(objWithSerializer.serializer, objWithSerializer.obj)
-
-    inline fun <reified T> encode(value: T) = encode(serializer(), value)
-
     fun <T> decode(deserializer: DeserializationStrategy<T>, data: ByteArray): T {
         val decoder = SmileDecoderAdapter(data)
         return decoder.decodeSerializableValue(deserializer)
     }
 
-    inline fun <reified T> decode(data: ByteArray): T = decode(serializer(), data)
-
     companion object : Smile(SmileConfig.DEFAULT)
 }
 
-// temp solution for testing
-class ObjWithSerializer<T>(val obj: T, val serializer: KSerializer<T>, val name: String?)
-inline fun <reified T> ObjWithSerializer(obj: T, name: String? = null) = ObjWithSerializer(obj, serializer<T>(), name)
+inline fun <reified T> Smile.encode(value: T) = encode(serializer(), value)
+inline fun <reified T> Smile.decode(data: ByteArray): T = decode(serializer(), data)
 

kotlinx-serialization-smile-core/src/commonMain/kotlin/io/github/vooft/kotlinsmile/SmileConfig.kt

@@ -1,9 +1,21 @@
 package io.github.vooft.kotlinsmile
 
 data class SmileConfig(
+    /**
+     * Write header with version and smile marker, if disabled can save 4 bytes and config will fall back to default
+     */
     val writeHeader: Boolean = true,
+    /**
+     * Share string values, if enabled can save space for repeated strings values, disabled by default
+     */
     val shareStringValue: Boolean,
+    /**
+     * Share property names, if enabled can save space for repeated property names, enabled by default
+     */
     val sharePropertyName: Boolean,
+    /**
+     * Write value as 7-bit encoded, if disabled can save ~14% space, disabled by default
+     */
     val writeValueAs7Bits: Boolean = true
 ) {
 
@@ -13,6 +25,9 @@ data class SmileConfig(
             require(!shareStringValue) { "String values are not shared by default, can not enable if write header is off" }
             require(writeValueAs7Bits) { "7-bit encoding is enabled by default, can not disable if write header is off" }
         }
+
+        require(writeHeader) { "Skipping header is not supported yet" }
+        require(writeValueAs7Bits) { "Writing binaries not as 7-bits is not supported yet" }
     }
 
     companion object {

kotlinx-serialization-smile-test/src/jvmTest/kotlin/io/github/vooft/kotlinsmile/jackson/JacksonCompatibilityTest.kt

@@ -4,7 +4,6 @@ import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.dataformat.smile.SmileFactory
 import com.fasterxml.jackson.dataformat.smile.SmileGenerator
 import io.github.oshai.kotlinlogging.KotlinLogging
-import io.github.vooft.kotlinsmile.ObjWithSerializer
 import io.github.vooft.kotlinsmile.Smile
 import io.github.vooft.kotlinsmile.SmileConfig
 import io.github.vooft.kotlinsmile.SmileMessage
@@ -13,7 +12,9 @@ import io.kotest.core.spec.style.ShouldSpec
 import io.kotest.datatest.withData
 import io.kotest.matchers.collections.shouldContainExactly
 import io.kotest.matchers.shouldBe
+import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.serializer
 import java.util.concurrent.ThreadLocalRandom
 
 // TODO: reorganize
@@ -119,7 +120,7 @@ class JacksonCompatibilityTest : ShouldSpec({
             logger.info { "E: " + expected.toHexString() }
             logger.info { "E: " + expected.toBinaryString() }
 
-            val actual = Smile.encode(it)
+            val actual = Smile.encodeObjWithSerializer(it)
             logger.info { "A: " + actual.toHexString() }
             logger.info { "A: " + actual.toBinaryString() }
             println()
@@ -153,7 +154,7 @@ class JacksonCompatibilityTest : ShouldSpec({
         ) {
             val expected = smileMapper.writeValueAsBytes(it.obj)
 
-            val actual = Smile.encode(it)
+            val actual = Smile.encodeObjWithSerializer(it)
 
             withClue("E: " + expected.toHexString() + "\n" + "A: " + actual.toHexString()) {
                 actual shouldBe expected
@@ -179,7 +180,7 @@ class JacksonCompatibilityTest : ShouldSpec({
             val encoded = smileMapperWithSharedNames.writeValueAsBytes(it.obj)
             println(encoded.toHexString())
 
-            val actual = smile.encode(it)
+            val actual = smile.encodeObjWithSerializer(it)
             println(actual.toHexString())
 
             actual.toHexString().replace(',', '\n') shouldBe encoded.toHexString().replace(',', '\n')
@@ -204,7 +205,7 @@ class JacksonCompatibilityTest : ShouldSpec({
             val encoded = smileMapperWithSharedNames.writeValueAsBytes(it.obj)
             println(encoded.toHexString())
 
-            val actual = smile.encode(it)
+            val actual = smile.encodeObjWithSerializer(it)
             println(actual.toHexString())
 
             actual.toHexString().replace(',', '\n') shouldBe encoded.toHexString().replace(',', '\n')
@@ -280,7 +281,7 @@ class JacksonCompatibilityTest : ShouldSpec({
             val encoded = smileMapperWithSharedNames.writeValueAsBytes(it.obj)
             println(encoded.toHexString())
 
-            val actual = smile.encode(it)
+            val actual = smile.encodeObjWithSerializer(it)
             println(actual.toHexString())
 
             actual.toHexString().replace(',', '\n') shouldBe encoded.toHexString().replace(',', '\n')
@@ -596,3 +597,8 @@ private fun ByteArray.toHexString() = joinToString(", ", "[", "]") { it.toUByte(
 private fun ByteArray.toBinaryString() = joinToString(", ", "[", "]") { it.toUByte().toString(2).padStart(8, '0') }
 
 private val logger = KotlinLogging.logger { }
+
+class ObjWithSerializer<T>(val obj: T, val serializer: KSerializer<T>, val name: String?)
+inline fun <reified T> ObjWithSerializer(obj: T, name: String? = null) = ObjWithSerializer(obj, serializer<T>(), name)
+
+fun <T> Smile.encodeObjWithSerializer(objWithSerializer: ObjWithSerializer<T>) = encode(objWithSerializer.serializer, objWithSerializer.obj)