Documentation rewrite - Get started page #3059
Conversation
daniCsorbaJB
changed the title
|
|
||
| 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.
There was a problem hiding this comment.
It's weird to start the dependencies section with Bazel. The first buildsystem mentioned should be our default — Gradle.
There was a problem hiding this comment.
You can use ### Other build systems section or something like that to mention Bazel
There was a problem hiding this comment.
We can also mention there for example our 'raw' compiler plugin artifact to be used with -Xplugin CLI arg. I can add it there later
There was a problem hiding this comment.
Also we can promote Amper here, adding instructions with it as well
There was a problem hiding this comment.
If there is a lot of stuff on different build systems it even makes sense to have a separate page for it (linked here). It would also help those who want to find instructions for setting it up in different build systems as they often would not expect it in a generic getting started page.
| </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?
There was a problem hiding this comment.
I think it's a bad idea. It is not always related to custom serializer, regular @Serializable classes can have named companions as well. I would expect separate page for Proguard then (linked here)
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.
|
|
||
| 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.
If there is a lot of stuff on different build systems it even makes sense to have a separate page for it (linked here). It would also help those who want to find instructions for setting it up in different build systems as they often would not expect it in a generic getting started page.
|
|
||
| ### Add the Kotlin serialization library to a multiplatform project | ||
|
|
||
| To use Kotlin serialization in multiplatform projects, add the JSON serialization library dependency to your common source set: |
There was a problem hiding this comment.
Maybe change it to "To use Kotlin serialization for JSON in multiplatform projects..." (and maybe: "This will automatically include the core serialization library.") Currently it implies that JSON is needed if a different format is used.
| 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.
Maybe explicitly state that the library supports multiple formats, but this tutorial focuses on JSON.
|
|
||
| In Kotlin, you can serialize objects to JSON using the `kotlinx.serialization` library. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
In between these lines, you may also want to remind readers that the plugin must be applied (annotation+plugin) → serializer. People don't read carefully, so leaving it out in this context is likely going to lead to some (too many) people not applying the plugin and wondering why it doesn't work.
This is the second part of the Kotlin Serialization rewrite.
Related YouTract ticket is: KT-80054 [Docs][Libraries] Get started with Kotlin Serialization)