doc(docs.topics.serialization): clear notes and add examples

dancer1325 · dancer1325 · commit fa940d54402b · 2025-05-16T16:47:58.000+02:00
diff --git a/docs/topics/examples/serialization/README.md b/docs/topics/examples/serialization/README.md
@@ -0,0 +1,27 @@
+## How has it been created?
+### Manually
+* download & paste | "../lib/"
+  * "kotlinx-serialization-core-jvm-1.6.0.jar"
+  * "kotlinx-serialization-json-jvm-1.6.0.jar"
+### Dependency Manager
+* TODO:
+
+## How to run it locally?
+### Manually
+* via IDE
+  * TODO: NOT display green click button
+* via CL
+  * | this path
+    * `kotlinc -cp "../lib/*" serialization.kt -include-runtime -d serialization.jar`
+      * Problems:
+        * Problem1: "warning: classpath entry points to a non-existent location: ../lib/*"
+          * Attempt1: `kotlinc -cp "../lib/kotlinx-serialization-json-jvm-1.6.0.jar:../lib/kotlinx-serialization-core-jvm-1.6.0.jar" serialization.kt -include-runtime -d serialization.jar`
+          * Solution: TODO:
+    * `java -jar serialization.jar`
+      * Problems:
+        * Problem1: "Caused by: java.lang.ClassNotFoundException: kotlinx.serialization.json.Json"
+          * Attempt1: `java -cp "../lib/kotlinx-serialization-json-jvm-1.6.0.jar:../lib/kotlinx-serialization-core-jvm-1.6.0.jar" -jar serialization.jar`
+          * Attempt2: `java -cp "../lib/kotlinx-serialization-json-jvm-1.6.0.jar:../lib/kotlinx-serialization-core-jvm-1.6.0.jar:serialization.jar" SerializationKt`
+          * Solution: TODO:
+### Dependency Manager
+* TODO:
diff --git a/docs/topics/examples/serialization/serialization.kt b/docs/topics/examples/serialization/serialization.kt
@@ -0,0 +1,21 @@
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.decodeFromString
+
+@Serializable
+data class Data(val a: Int, val b: String)
+
+fun main() {
+    // 1. serialize
+    val classInstance = Json.encodeToString(Data(42, "str"))
+    println("1. serialize - classInstance " + classInstance)
+
+    val dataList = listOf(Data(42, "str"), Data(12, "test"))
+    val jsonList = Json.encodeToString(dataList)
+    println("1. serialize - jsonList " + jsonList)
+
+    // 2. deserialize
+    val deserialize = Json.decodeFromString<Data>("""{"a":42, "b": "str"}""")
+    println("2. deserialize - deserialize " + deserialize)
+}
diff --git a/docs/topics/serialization.md b/docs/topics/serialization.md
@@ -1,128 +1,120 @@
 [//]: # (title: Serialization)
 
-_Serialization_ is the process of converting data used by an application to a format that can be transferred over a network
-or stored in a database or a file. In turn, _deserialization_ is the opposite process of reading data from an external source
-and converting it into a runtime object. Together, they are essential to most applications that exchange
-data with third parties. 
-
-Some data serialization formats, such as [JSON](https://www.json.org/json-en.html) and 
-[protocol buffers](https://developers.google.com/protocol-buffers) are particularly common. Being language-neutral and
-platform-neutral, they enable data exchange between systems written in any modern language.
-
-In Kotlin, data serialization tools are available in a separate component, [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization).
-It consists of several parts: the `org.jetbrains.kotlin.plugin.serialization` Gradle plugin, [runtime libraries](#libraries),
-and compiler plugins.
-
-Compiler plugins, `kotlinx-serialization-compiler-plugin` and `kotlinx-serialization-compiler-plugin-embeddable`,
-are published directly to Maven Central. The second plugin is designed for working with the `kotlin-compiler-embeddable`
-artifact, which is the default option for scripting artifacts. Gradle adds compiler plugins to your projects as compiler arguments.
+* _Serialization_
+  * := process of data used by an application -- is converted to a -- format / can be
+    * transferred -- over a -- network
+    * stored | database OR file
+  * formats
+    * [JSON](https://www.json.org/json-en.html)
+    * [protocol buffers](https://developers.google.com/protocol-buffers)
+
+* _deserialization_
+  * := process of data | external source -- is 
+    * read
+    * converted it into a -- runtime object
+ 
+* allows
+  * being language-neutral & platform-neutral 
+
+* uses
+  * MOST applications / exchange data -- with -- third parties
 
 ## Libraries
 
-`kotlinx.serialization` provides sets of libraries for all supported platforms – JVM, JavaScript, Native – and for various
-serialization formats – JSON, CBOR, protocol buffers, and others. You can find the complete list of supported serialization
-formats [below](#formats).
-
-All Kotlin serialization libraries belong to the `org.jetbrains.kotlinx:` group. Their names start with `kotlinx-serialization-`
-and have suffixes that reflect the serialization format. Examples:
-* `org.jetbrains.kotlinx:kotlinx-serialization-json` provides JSON serialization for Kotlin projects.
-* `org.jetbrains.kotlinx:kotlinx-serialization-cbor` provides CBOR serialization.
-
-Platform-specific artifacts are handled automatically; you don't need to add them manually. Use the same dependencies in
-JVM, JS, Native, and multiplatform projects.
-
-Note that the `kotlinx.serialization` libraries use their own versioning structure, which doesn't match Kotlin's versioning.
-Check out the releases on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases) to find the latest versions.
-
-## Formats
-
-`kotlinx.serialization` includes libraries for various serialization formats:
-
-* [JSON](https://www.json.org/): [`kotlinx-serialization-json`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#json)
-* [Protocol buffers](https://developers.google.com/protocol-buffers): [`kotlinx-serialization-protobuf`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#protobuf)
-* [CBOR](https://cbor.io/): [`kotlinx-serialization-cbor`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#cbor)
-* [Properties](https://en.wikipedia.org/wiki/.properties): [`kotlinx-serialization-properties`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties)
-* [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md): [`kotlinx-serialization-hocon`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#hocon) (only on JVM)
-
-Note that all libraries except JSON serialization (`kotlinx-serialization-json`) are [Experimental](components-stability.md),
-which means their API can be changed without notice.
-
-There are also community-maintained libraries that support more serialization formats, such as [YAML](https://yaml.org/)
-or [Apache Avro](https://avro.apache.org/). For detailed information about available serialization formats, see the 
-[`kotlinx.serialization` documentation](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md).
-
-## Example: JSON serialization
-
-Let's take a look at how to serialize Kotlin objects into JSON.
-
-### Add plugins and dependencies
-
-Before starting, you must configure your build script so that you can use Kotlin serialization tools in your project:
-
-1. Apply the Kotlin serialization Gradle plugin `org.jetbrains.kotlin.plugin.serialization` (or `kotlin("plugin.serialization")`
-in the Kotlin Gradle DSL).
-
-    <tabs group="build-script">
-    <tab title="Kotlin" group-key="kotlin">
-
-    ```kotlin
+* `org.jetbrains.kotlinx:` group, 
+  * ALL Kotlin serialization libraries
+  * `kotlinx-serialization-ConcreteSerializationFormat`
+    * artifact names
+    * _Examples:_
+      * `org.jetbrains.kotlinx:kotlinx-serialization-json`
+        * JSON serialization
+      * `org.jetbrains.kotlinx:kotlinx-serialization-cbor`
+        * CBOR serialization
+    * support ALL platforms
+      * == 1 artifact / ALL platforms
+
+* [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)
+  * == 👀SET of data serialization libraries 👀 /
+    * SEPARATE component
+      * == ❌NOT | kotlin ❌
+    * supports
+      * platforms
+        * JVM
+        * JavaScript
+        * Native
+      * serialization formats
+        * official
+          * JSON, 
+          * CBOR,
+          * protocol buffers,
+          * ...
+        * [community](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md)
+    * versioning != Kotlin's versioning
+  * == `org.jetbrains.kotlin.plugin.serialization` Gradle plugin + [runtime libraries](#libraries) + compiler plugins
+    * compiler plugins
+      * are
+        * `kotlinx-serialization-compiler-plugin`
+        * `kotlinx-serialization-compiler-plugin-embeddable`
+          * 's goal
+            * use + `kotlin-compiler-embeddable` artifact 
+      * published DIRECTLY | Maven Central
+      * | Gradle,
+        * if you want to add | your projects -> add -- as -- compiler arguments 
+  * `kotlin-compiler-embeddable` artifact
+    * allows
+      * scripting artifacts
+        * indeed, default option
+
+## _Example:_ JSON serialization
+
+* goal
+  * serialize Kotlin objects (class instances, collections, ...) -- into -> JSON
+
+### steps
+#### 1. Add plugins & dependencies
+
+1. add Kotlin serialization Gradle plugin
+    ```kotlin,tittle=build.gradle.kts
     plugins {
-        kotlin("jvm") version "%kotlinVersion%"
-        kotlin("plugin.serialization") version "%kotlinVersion%"
-    }
+      kotlin("jvm") version "%kotlinVersion%"
+      kotlin("plugin.serialization") version "%kotlinVersion%"
+    }  
     ```
 
-    </tab>
-    <tab title="Groovy" group-key="groovy">
-
-    ```groovy
+    ```groovy, title=build.gradle
     plugins {
         id 'org.jetbrains.kotlin.jvm' version '%kotlinVersion%'
         id 'org.jetbrains.kotlin.plugin.serialization' version '%kotlinVersion%'  
     }
     ```
 
-    </tab>
-    </tabs>
-
-2. Add the JSON serialization library dependency:`org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%`
-
-    <tabs group="build-script">
-    <tab title="Kotlin" group-key="kotlin">
+2. add JSON serialization library dependency
 
-    ```kotlin
+    ```kotlin,tittle=build.gradle.kts
     dependencies {
         implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%")
     } 
     ```
 
-    </tab>
-    <tab title="Groovy" group-key="groovy">
-
-    ```groovy
+    ```groovy, title=build.gradle
     dependencies {
         implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%'
     } 
     ```
 
-    </tab>
-    </tabs>
+#### 2. Serialize & deserialize JSON
 
-Now you're ready to use the serialization API in your code. The API is located in the `kotlinx.serialization` package
-and its format-specific subpackages, such as `kotlinx.serialization.json`.
-
-### Serialize and deserialize JSON
-
-1. Make a class serializable by annotating it with `@Serializable`.
-
-```kotlin
-import kotlinx.serialization.Serializable
+1. | class,
+   1. annotate with `@Serializable`
 
-@Serializable
-data class Data(val a: Int, val b: String)
-```
+    ```kotlin
+    import kotlinx.serialization.Serializable
+    
+    @Serializable
+    data class Data(val a: Int, val b: String)
+    ```
 
-2. Serialize an instance of this class by calling `Json.encodeToString()`.
+2. if you want to serialize a class' instance -> call `Json.encodeToString()`
 
 ```kotlin
 import kotlinx.serialization.Serializable
@@ -133,22 +125,14 @@ import kotlinx.serialization.encodeToString
 data class Data(val a: Int, val b: String)
 
 fun main() {
+   // serialize a class instance 
    val json = Json.encodeToString(Data(42, "str"))
+   val dataList = listOf(Data(42, "str"), Data(12, "test"))
+   val jsonList = Json.encodeToString(dataList)
 }
 ```
 
-As a result, you get a string containing the state of this object in the JSON format: `{"a": 42, "b": "str"}`
-
-> You can also serialize object collections, such as lists, in a single call:
-> 
-> ```kotlin
-> val dataList = listOf(Data(42, "str"), Data(12, "test"))
-> val jsonList = Json.encodeToString(dataList)
-> ```
-> 
-{type="note"}
-
-3. Use the `decodeFromString()` function to deserialize an object from JSON:
+3. if you want from JSON -- deserialize into -- an object -> use `decodeFromString()`  
 
 ```kotlin
 import kotlinx.serialization.Serializable
@@ -159,21 +143,11 @@ import kotlinx.serialization.decodeFromString
 data class Data(val a: Int, val b: String)
 
 fun main() {
+   // deserialize 
    val obj = Json.decodeFromString<Data>("""{"a":42, "b": "str"}""")
 }
 ```
 
-That's it! You have successfully serialized objects into JSON strings and deserialized them back into objects.
-
 ## What's next
 
-For more information about serialization in Kotlin, see the [Kotlin Serialization Guide](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serialization-guide.md).
-
-You can explore different aspects of Kotlin serialization in the following resources:
-
-* [Learn more about Kotlin serialization and its core concepts](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/basic-serialization.md)
-* [Explore the built-in serializable classes of Kotlin](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/builtin-classes.md)
-* [Look at serializers in more detail and learn how to create custom serializers](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md)
-* [Discover how polymorphic serialization is handled in Kotlin](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/polymorphism.md#open-polymorphism)
-* [Look into the various JSON features handling Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/json.md#json-elements)
-* [Learn more about the experimental serialization formats supported by Kotlin](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats.md)
+* see [Kotlin Serialization Guide](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serialization-guide.md).
