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.
Not true about primary constructor, I've already mentioned that in one of the reviews
| allowing a class to be converted to and from formats such as JSON. | ||
|
|
||
| In Kotlin, only properties with backing fields are serialized. | ||
| Properties defined with [accessors](properties.md) or delegated properties without backing fields are excluded from serialization: |
There was a problem hiding this comment.
You can have accessors and backing fields too: https://kotlinlang.org/docs/properties.html#backing-fields
I suggest just giving link to the definition of backing field here to avoid further confusion, as repeating "Kotlin only generates backing fields if you use the default getter or setter, or if you use field in at least one custom accessor." may be too long
|
|
||
| In Kotlin, only properties with backing fields are serialized. | ||
| Properties defined with [accessors](properties.md) or delegated properties without backing fields are excluded from serialization: | ||
|
|
There was a problem hiding this comment.
Delegated properties cannot have backing field at all btw, so avoid phrases like "delegated properties without backing fields"
| // Declares a property with a backing field - serialized | ||
| var name: String | ||
| ) { | ||
| // Declares a property with a backing field - serialized |
There was a problem hiding this comment.
Is "Declares ..." our standard for technical writing? I do not remember seeing it. IMO, it is quite redundant, as we know that this line is a declaration, so we get smth like "Declaration declares a property with a backing field"
| {kotlin-runnable="true"} | ||
|
|
||
| Kotlin Serialization natively supports nullable properties. | ||
| Like [other _default values_](#set-default-values-for-optional-properties), `null` values aren't encoded in the JSON output: |
There was a problem hiding this comment.
I get the following tooltip on hover:
IMO it's out of place and confusing. Also, link points to "Set default values for optional properties" which doesn't mention dropping of default values. Maybe it should point to "Manage the serialization of default properties with @EncodedDefault" instead?
| //sampleStart | ||
| @Serializable | ||
| // The Box<T> class can be used with built-in types like Int | ||
| // Alternatively, with user-defined types like Project |
There was a problem hiding this comment.
"or with @serializable user-defined types like Project"
|
|
||
| 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 shorter or more descriptive in the serialized output: |
There was a problem hiding this comment.
I do not think we should advise users making their names shorter
|
|
||
| ### Validate data in the primary constructor | ||
|
|
||
| You can validate constructor parameters before storing it in properties to ensure that a class is serializable and invalid data is rejected during deserialization. |
There was a problem hiding this comment.
"A deserialization process works like a regular constructor in Kotlin and calls all init blocks" — is an important detail, you didn't have to remove it
| ``` | ||
| {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
| > | ||
| {style="tip"} | ||
|
|
||
| ### Manage the serialization of default properties with `@EncodedDefault` |
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