more docs

This commit is contained in:
Sergey Chernov 2025-01-18 04:28:11 +03:00
parent 39c5f1f586
commit 38751b5df6

View File

@ -3,22 +3,19 @@ package net.sergeych.bipack
import kotlinx.serialization.SerialInfo import kotlinx.serialization.SerialInfo
/** /**
* If this annotation is presented in some @Serializable class definition, its instances * To be used with [kotlinx.serialization.Serializable]. Allows serialized classes to be
* will be serialized with the leading number of fields. This allows extending class later * extended by _adding members with default initializers_ __to the end of the constructor list__.
* providing new parameters __to the end of the class__ and _with default values__.
* *
* __IMPORTANT NOTE__. Since version 0.0.7 it's been also possible to use default values * This annotation makes Bipack to insert fields count before the
* for non-serialized fields after the end-of-data. If the source reports it correctly, e.g. * serialized data. It then checks it on deserializing to fill not serialized fields will
* [net.sergeych.bintools.DataSource.isEnd] returns true, the unset fields are initialized * default values.
* 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.
* *
* Whe deserializing such instances from previous version binaries, the new parameters * Note that since 0.0.7 the same behavior could be achieved by serializing each instance in the
* will get default values. * 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 * _Please note that without this annotation it could be impossible to deserialize old versions of
* breaking compatibility with existing serialized data. * the class, in particular, in array, inner fields, etc._
*/ */
@Target(AnnotationTarget.CLASS) @Target(AnnotationTarget.CLASS)
@SerialInfo @SerialInfo