Documentation rewrite - Get started page #3059
Conversation
daniCsorbaJB
changed the title
|
|
||
| ```xml | ||
| <properties> | ||
| <kotlin.version>%kotlinVersion%</kotlin.version> |
There was a problem hiding this comment.
Indentation is a little off — versions should be one tab more to the right
|
|
||
| To include the `kotlinx.serialization` library in your project, add the corresponding plugin and dependency configuration based on your build tool. | ||
|
|
||
| > To set up the Kotlin compiler plugin for Bazel, see the example provided in the [rules_kotlin repository](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization). |
There was a problem hiding this comment.
I think this note should be moved after Gradle/Maven sections
There was a problem hiding this comment.
hmm 🤔 my issue with that is that way it might seem like it's related to Maven. Since it's just a note without specific instructions I left it in the generic part of the doc.
| </dependencies> | ||
| ``` | ||
|
|
||
| ### Add the Kotlin serialization library to a multiplatform project |
There was a problem hiding this comment.
We also mention Proguard rules (specific for Android) in the README.md. Do you plan to add them here?
There was a problem hiding this comment.
good question 🤔
I think we could add it to the Create custom serializer page (where we talk about serializer() and companion objects) Although, we could place a link to that part of the page here. 🤔
What do you think?
|
|
||
| ## Serialize objects to JSON | ||
|
|
||
| Serialization is the process of converting an object into a format that can be easily stored or transmitted, such as JSON. |
There was a problem hiding this comment.
This sentence repeats the one the whole document is started with
There was a problem hiding this comment.
fair point - seems pretty redundant - removed it 👍
|
|
||
| Let's look at an example: | ||
|
|
||
| 1. Import the necessary serialization libraries: |
There was a problem hiding this comment.
"Import libraries" sounds not very technically correct. Library is something you can depend on, while you import declarations from the said library
| data class Data(val a: Int, val b: String) | ||
| ``` | ||
|
|
||
| > The `@Serializable` annotation enables default serialization of all properties in the primary constructor. |
There was a problem hiding this comment.
We serialize all properties with backing fields, not only the primary constructor ones.
| ``` | ||
|
|
||
| > The `@Serializable` annotation enables default serialization of all properties in the primary constructor. | ||
| > You can customize serialization behavior with custom constructors, optional properties, and more. |
There was a problem hiding this comment.
What 'custom constructors' you mean here? I don't quite understand.
There was a problem hiding this comment.
hmm 🤔 I agree. The original intention was to fit info about non-default constructor for deserialization, but it reads really weird here.
What do you think about this version:
You can customize serialization behavior with property-level annotations, optional properties, and more.
(like @SerialName @Transient etc)
| 3. Use the [`Json.encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function to serialize an instance of this class: | ||
|
|
||
| ```kotlin | ||
| // Imports the necessary libraries for serialization and JSON handling |
There was a problem hiding this comment.
Same comment about declarations here
|
|
||
| Congratulations! You have successfully serialized an object to JSON and deserialized it back into an object in Kotlin! | ||
|
|
||
| ## What's next |
There was a problem hiding this comment.
Should we add whole chapters to the TOC again? Or maybe add a separate page after all with the text like "See all chapters in this guide here — link-to-toc.md"
There was a problem hiding this comment.
🤔
Since this isn't an introductory page, we should only list logical next steps here rather than broad exploration. (The ToC will be on the left side of the screen so if someone wants to wander, they can do so)
My thoughts were that Built-in types are the simplest next topic, making them a natural continuation point.
We’ve also mentioned the @Serializable annotation, so linking to a page that explains it in detail might also be a sensible continuation.
Lastly, because the example on this page uses JSON, the JSON serialization overview might also be an appropriate next step.
This is the second part of the Kotlin Serialization rewrite.
Related YouTract ticket is: KT-80054 [Docs][Libraries] Get started with Kotlin Serialization)