From 7bf105eb3b730831b14a716786bc50605af6414a Mon Sep 17 00:00:00 2001 From: Vsevolod Tolstopyatov Date: Thu, 10 Aug 2023 15:03:08 +0200 Subject: 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 --- core/commonMain/src/kotlinx/serialization/Annotations.kt | 9 +++++---- 1 file 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. -- cgit v1.2.3