feat: adding the Serialize classes page #3097
Conversation
| @@ -0,0 +1,505 @@ | |||
| [//]: # (title: Serialize classes) | |||
|
|
|||
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation in Kotlin enables the serialization of all properties in classes defined by the primary constructor. | |||
There was a problem hiding this comment.
nice, good point - changed it to properties with backing fields here as well 👍
| ``` | ||
| {kotlin-runnable="true"} | ||
|
|
||
| ### Set default values for optional properties |
There was a problem hiding this comment.
Summing up all commentaries above, I think this section should be put much earlier — before dropping nulls and mentioning that initializers are not always called for optionals. I think it even worth its own sub-section in the navigation pane on the right. E.g.:
- Optional properties
- setting default value
- default values are dropped by default (example with null)
- initializer is not always called
- controlling behavior with @EncodeDefault
- making properties @Required
There was a problem hiding this comment.
I really like the idea 👍 I restructured it
I'm a bit unsure about @Required and @Transient. They mention default values, but I think those might be a better fit in ## Customize class serialization.
But moving everything else about Optional properties solves a lot of issues 👍
There was a problem hiding this comment.
Transient indeed fits into ## Customize class serialization.. @Required directly affects properties with optional values (and doesn't make sense without one), so I think it's still better to place it here.
| @@ -0,0 +1,505 @@ | |||
| [//]: # (title: Serialize classes) | |||
|
|
|||
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation in Kotlin enables the serialization of all properties in classes defined by the primary constructor. | |||
There was a problem hiding this comment.
nice, good point - changed it to properties with backing fields here as well 👍
sandwwraith
left a comment
sandwwraith
left a comment
There was a problem hiding this comment.
I do not know whether we'll finish whole review before mid-December (I expect next release of serialization there), but we can leave opt-in note for now and delete it later.
Besides that, please fix "Defines..." wording and my other comment and we're good to go
sarahhaggarty
left a comment
sarahhaggarty
left a comment
There was a problem hiding this comment.
Looks great! I have some suggestions for you to consider and a couple clarification questions :)
| [//]: # (title: Serialize classes) | ||
|
|
||
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields. | ||
| You can further customize this behavior to fit your specific needs. |
There was a problem hiding this comment.
| You can further customize this behavior to fit your specific needs. | |
| You can customize this behavior to fit your specific needs. |
| @@ -0,0 +1,516 @@ | |||
| [//]: # (title: Serialize classes) | |||
|
|
|||
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields. | |||
There was a problem hiding this comment.
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields. | |
| By default, the [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation serializes all class properties that have backing fields. |
What do you think of this version?
|
|
||
| The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields. | ||
| You can further customize this behavior to fit your specific needs. | ||
| This page covers various serialization techniques, showing you how to specify which properties are serialized and how the serialization process is managed. |
There was a problem hiding this comment.
| This page covers various serialization techniques, showing you how to specify which properties are serialized and how the serialization process is managed. | |
| This page covers various serialization techniques, showing you how to specify which properties are serialized, and how the serialization process is managed. |
Is the process managed by the library?
| ``` | ||
| {kotlin-runnable="true" id="serialize-annotation-example"} | ||
|
|
||
| ### Serialization of class references |
There was a problem hiding this comment.
What do you think about "Serialize class references" as a header? So that the header style matches the others on the page?
| > | ||
| {style="tip"} | ||
|
|
||
| ### Serialization of repeated object references |
There was a problem hiding this comment.
What do you think about "Serialize repeated object references" as a header? So that the header style matches the others on the page?
|
|
||
| ## Customize class serialization | ||
|
|
||
| Kotlin Serialization provides several ways to modify how classes are serialized. |
There was a problem hiding this comment.
What do you think about "control" instead of "modify"?
|
|
||
| You can customize these names, called _serial names_, | ||
| with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation. | ||
| Use it to make a property name more descriptive in the serialized output: |
There was a problem hiding this comment.
Here you say that you should use it to make the property more descriptive. But in the example you abbreviate it. So maybe we should change the wording or the example?
| A class annotated with `@Serializable` must declare all parameters in its primary constructor as properties. | ||
|
|
||
| If you need to perform additional initialization logic before assigning values to properties, use a secondary constructor. | ||
| The primary constructor can remain private and handle property initialization. |
There was a problem hiding this comment.
| The primary constructor can remain private and handle property initialization. | |
| The primary constructor can remain `private` and handle property initialization. |
|
|
||
| ### Validate data in the primary constructor | ||
|
|
||
| After deserialization, the `kotlinx.serialization` plugin runs the class's initializer blocks, |
There was a problem hiding this comment.
Could you add a link here to the Kotlin section about initializer blocks? https://kotlinlang.org/docs/classes.html#initializer-blocks
| You can exclude a property from serialization with the [`@Transient`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-transient/) annotation. | ||
| Transient properties must have a default value. | ||
|
|
||
| If you explicitly specify a value for a transient property in the input, even if it matches the default value, a `JsonDecodingException` is thrown: |
There was a problem hiding this comment.
Again, I'm not sure what "input" is referring to exactly here 🤔
This is the fourth part of the Kotlin Serialization rewrite task.
Related YouTract ticket is here: KT-81889 [Docs] Create a Serialize classes page for kotlinx.serialization