From 38751b5df620ff35f390daec71a50a182ed10080 Mon Sep 17 00:00:00 2001 From: sergeych Date: Sat, 18 Jan 2025 04:28:11 +0300 Subject: [PATCH] more docs --- .../kotlin/net.sergeych.bipack/annotations.kt | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/src/commonMain/kotlin/net.sergeych.bipack/annotations.kt b/src/commonMain/kotlin/net.sergeych.bipack/annotations.kt index 7be187c..8f4f911 100644 --- a/src/commonMain/kotlin/net.sergeych.bipack/annotations.kt +++ b/src/commonMain/kotlin/net.sergeych.bipack/annotations.kt @@ -3,22 +3,19 @@ package net.sergeych.bipack import kotlinx.serialization.SerialInfo /** - * If this annotation is presented in some @Serializable class definition, its instances - * will be serialized with the leading number of fields. This allows extending class later - * providing new parameters __to the end of the class__ and _with default values__. + * To be used with [kotlinx.serialization.Serializable]. Allows serialized classes to be + * extended by _adding members with default initializers_ __to the end of the constructor list__. * - * __IMPORTANT NOTE__. Since version 0.0.7 it's been also possible to use default values - * for non-serialized fields after the end-of-data. If the source reports it correctly, e.g. - * [net.sergeych.bintools.DataSource.isEnd] returns true, the unset fields are initialized - * with default value. This approach ___is not working when the loading instance is not the last - * in the deciding array!___, still it is useful to decode isolated objects. We recommend to - * use [Extendable] where needed and possible. + * This annotation makes Bipack to insert fields count before the + * serialized data. It then checks it on deserializing to fill not serialized fields will + * default values. * - * Whe deserializing such instances from previous version binaries, the new parameters - * will get default values. + * Note that since 0.0.7 the same behavior could be achieved by serializing each instance in the + * array as Bipack correctly processes end-of-data by filling missing fields with default values, + * using `Extendable` is more convenient and save some space, most of the time. * - * Serialized data of classes not market as ExtendableFormat could not be changed without - * breaking compatibility with existing serialized data. + * _Please note that without this annotation it could be impossible to deserialize old versions of + * the class, in particular, in array, inner fields, etc._ */ @Target(AnnotationTarget.CLASS) @SerialInfo