Expand @SerialInfo doc with information on targets (#1926)

Kotlin · May 5, 2022 · a46299e · a46299e
1 parent 85986d8
commit a46299e
Showing 1 changed file with 6 additions and 1 deletion.
diff --git a/core/commonMain/src/kotlinx/serialization/Annotations.kt b/core/commonMain/src/kotlinx/serialization/Annotations.kt
@@ -181,7 +181,12 @@ public annotation class EncodeDefault(val mode: Mode = Mode.ALWAYS) {
 /**
  * Meta-annotation that commands the compiler plugin to handle the annotation as serialization-specific.
  * Serialization-specific annotations are preserved in the [SerialDescriptor] and can be retrieved
- * during serialization process with [SerialDescriptor.getElementAnnotations].
+ * during serialization process with [SerialDescriptor.getElementAnnotations] for properties annotations
+ * and [SerialDescriptor.annotations] for class annotations.
+ *
+ * It is recommended to explicitly specify target for serial info annotations, whether it is [AnnotationTarget.PROPERTY], [AnnotationTarget.CLASS], or both.
+ * Keep in mind that Kotlin compiler prioritizes [function parameter target][AnnotationTarget.VALUE_PARAMETER] over [property target][AnnotationTarget.PROPERTY],
+ * so serial info annotations used on constructor-parameters-as-properties without explicit declaration-site or use-site target are not preserved.
  */
 @Target(AnnotationTarget.ANNOTATION_CLASS)
 @Retention(AnnotationRetention.BINARY)