diff options
| author | Vsevolod Tolstopyatov <qwwdfsad@gmail.com> | 2023-08-10 15:03:08 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-08-10 15:03:08 +0200 |
| commit | 7bf105eb3b730831b14a716786bc50605af6414a (patch) | |
| tree | e9182a47a73b18afc7c8b8c4d91ea1682983dfa5 | |
| parent | e68f08ed02305fd536abcaf9e289dc72ca105324 (diff) | |
| download | kotlinx.serialization-7bf105eb3b730831b14a716786bc50605af6414a.tar.gz | |
Mark @SerialName, @Required and @Transient with @MustBeDocumented (#2407)
Documentation for @Serializable classes describes not only the class itself, but its serializable form, which might/is used as the reference for external API/REST-like documentation.
Thus, all properties that constrain or change serialized form are explicitly marked with @MBD in order to highlight that fact in the documentation
Fixes #2386
| -rw-r--r-- | core/commonMain/src/kotlinx/serialization/Annotations.kt | 9 |
1 files changed, 5 insertions, 4 deletions
diff --git a/core/commonMain/src/kotlinx/serialization/Annotations.kt b/core/commonMain/src/kotlinx/serialization/Annotations.kt index 02db3837..67104dc3 100644 --- a/core/commonMain/src/kotlinx/serialization/Annotations.kt +++ b/core/commonMain/src/kotlinx/serialization/Annotations.kt @@ -1,9 +1,7 @@ /* - * Copyright 2017-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + * Copyright 2017-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. */ -@file:Suppress("NO_EXPLICIT_VISIBILITY_IN_API_MODE_WARNING") // Parameters of annotations should probably be ignored, too - package kotlinx.serialization import kotlinx.serialization.descriptors.* @@ -149,6 +147,7 @@ public annotation class Serializer( * If a name of class or property is overridden with this annotation, original source code name is not available for the library. * Tools like `JsonNamingStrategy` and `ProtoBufSchemaGenerator` would see and transform [value] from [SerialName] annotation. */ +@MustBeDocumented @Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS) // @Retention(AnnotationRetention.RUNTIME) still runtime, but KT-41082 public annotation class SerialName(val value: String) @@ -156,6 +155,7 @@ public annotation class SerialName(val value: String) /** * Indicates that property must be present during deserialization process, despite having a default value. */ +@MustBeDocumented @Target(AnnotationTarget.PROPERTY) // @Retention(AnnotationRetention.RUNTIME) still runtime, but KT-41082 public annotation class Required @@ -164,6 +164,7 @@ public annotation class Required * Marks this property invisible for the whole serialization process, including [serial descriptors][SerialDescriptor]. * Transient properties must have default values. */ +@MustBeDocumented @Target(AnnotationTarget.PROPERTY) // @Retention(AnnotationRetention.RUNTIME) still runtime, but KT-41082 public annotation class Transient @@ -189,6 +190,7 @@ public annotation class Transient * @see EncodeDefault.Mode.ALWAYS * @see EncodeDefault.Mode.NEVER */ +@MustBeDocumented @Target(AnnotationTarget.PROPERTY) @ExperimentalSerializationApi public annotation class EncodeDefault(val mode: Mode = Mode.ALWAYS) { @@ -267,7 +269,6 @@ public annotation class SerialInfo @ExperimentalSerializationApi public annotation class InheritableSerialInfo - /** * Instructs the plugin to use [ContextualSerializer] on a given property or type. * Context serializer is usually used when serializer for type can only be found in runtime. |