more docs

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