Documentation rewrite - Get started page #3059
Conversation
daniCsorbaJB
changed the title
There was a problem hiding this comment.
I've realized we have a tip
We also provide kotlinx-serialization-core artifact that contains all serialization API but does not have a bundled serialization format with it
in our current README.md, which is missing from this document.
Perhaps it is better to place it in the serialization.md/Kotlin serialization libraries or Supported serialization formats section in the form of
Pro tip: if you do not want a dependency on a particular format (e.g., you are writing your own serialization format), you can use
kotlinx-serialization-corelibrary.
I really like the second option — let's go with that (let's put it in the supported serialization formats page) |
So, do you plan to address it? |
| @@ -0,0 +1,281 @@ | |||
| [//]: # (title: Get started with Kotlin serialization) | |||
|
|
|||
| [Serialization](serialization.md) converts objects into a format that can be stored or transmitted and later reconstructed. | |||
There was a problem hiding this comment.
| [Serialization](serialization.md) converts objects into a format that can be stored or transmitted and later reconstructed. | |
| [Serialization](serialization.md) converts objects into a format you can store or transmit and later reconstruct. |
What do you think about making this more active?
| [Serialization](serialization.md) converts objects into a format that can be stored or transmitted and later reconstructed. | ||
|
|
||
| Kotlin serialization supports multiple formats. | ||
| This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization and how to serialize and deserialize objects in JSON format. |
There was a problem hiding this comment.
| This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization and how to serialize and deserialize objects in JSON format. | |
| This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization, and how to serialize and deserialize objects in JSON format. |
| Kotlin serialization supports multiple formats. | ||
| This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization and how to serialize and deserialize objects in JSON format. | ||
|
|
||
| ## Add plugins and dependencies for Kotlin serialization to your project |
There was a problem hiding this comment.
| ## Add plugins and dependencies for Kotlin serialization to your project | |
| ## Add plugins and dependencies |
I think we can shorten this since it's clear we're talking about the Kotlin serialization library.
| > | ||
| {style="tip"} | ||
|
|
||
| ### Add the Kotlin serialization library to a multiplatform project |
There was a problem hiding this comment.
| ### Add the Kotlin serialization library to a multiplatform project | |
| ### Add the library to a multiplatform project |
| ### Configure R8 for Kotlin serialization in Android projects {initial-collapse-state="collapsed" collapsible="true"} | ||
|
|
||
| The Kotlin serialization library includes default [ProGuard rules](https://github.com/Kotlin/kotlinx.serialization/blob/master/rules/common.pro), so you don't need additional setup to keep serializers for all serializable classes after shrinking. | ||
| These rules don't apply to classes with named companion objects. |
There was a problem hiding this comment.
| These rules don't apply to classes with named companion objects. | |
| However, these rules don't apply to classes with named companion objects. |
|
|
||
| To make a class serializable, you need to mark it with the [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation. | ||
| This annotation instructs the compiler to generate the code required for serializing and deserializing instances of the class. | ||
| For more information, see [The @Serialization annotation](serialization-customization-options.md#the-serializable-annotation). |
There was a problem hiding this comment.
| For more information, see [The @Serialization annotation](serialization-customization-options.md#the-serializable-annotation). | |
| For more information, see [The `@Serialization` annotation](serialization-customization-options.md#the-serializable-annotation). |
|
|
||
| ```kotlin | ||
| @Serializable | ||
| data class Data(val a: Int, val b: String) |
There was a problem hiding this comment.
Could you improve the example by making it more real world like? For example, the data class could be called Book and have title which is a String and yearPublished as an Int.
| ``` | ||
| {kotlin-runnable="true"} | ||
|
|
||
| Congratulations! You have successfully serialized an object to JSON and deserialized it back into an object in Kotlin! |
There was a problem hiding this comment.
| Congratulations! You have successfully serialized an object to JSON and deserialized it back into an object in Kotlin! | |
| Congratulations! You have successfully serialized an object to JSON and deserialized it back into an object in Kotlin. |
Nitpick. Just to make it sound not so excitable :)
|
|
||
| ## What's next | ||
| * Learn how to serialize standard types, including built-in types like numbers and strings, in [Serialize built-in types](serialization-serialize-builtin-types.md). |
There was a problem hiding this comment.
By "standard" do you mean basic types?
| ## What's next | ||
| * Learn how to serialize standard types, including built-in types like numbers and strings, in [Serialize built-in types](serialization-serialize-builtin-types.md). | ||
| * Discover how to customize class serialization and adjust the default behavior of the `@Serializable` annotation in the [Serialize classes](serialization-customization-options.md) section. |
There was a problem hiding this comment.
Will it be a section in this page? Or is it a page itself?
| // {"a":42,"b":"str"} | ||
| } | ||
| ``` | ||
| {kotlin-runnable="true"} |
There was a problem hiding this comment.
Can you give it an ID so we can see how many people run it in GA?
| // Data(a=42, b=str) | ||
| } | ||
| ``` | ||
| {kotlin-runnable="true"} |
There was a problem hiding this comment.
It would also be great to have an ID here.
This is the second part of the Kotlin Serialization rewrite.
Related YouTract ticket is: KT-80054 [Docs][Libraries] Get started with Kotlin Serialization)