upgraded to k1.8, upgraded stools, added more docs on codecs

src/commonMain/kotlin/net.sergeych.bintools/smartint.kt

@@ -21,31 +21,50 @@ import net.sergeych.bintools.*
  * |   10  |    64  |   ---     |
  *
  * In other words, except for very small numbers smartint
- * gives 1 bit gain. So, full sized 64 bits with smartint takes
- * 9 bytes, while varint needs 10. This could be important.
+ * gives 1 data bit gain for the same packed byte size. For example,
+ * full size 64 bits number with smartint takes one byte less (9 bytes vs. 10 in Varint).
  *
- * Encoding is the following:
+ * So, except for values in range 32..63 it gives same or better byte size effectiveness
+ * than `Varint`. In particular:
  *
- *    Byte 0:  bits 0..1  : type
- *             bits 2..7 : v0
+ * The effect of it could be interpreted as:
  *
- * Then depending on the type:
+ * | number values | size  |
+ * |:--------------|:------:|
+ * | 0..31 | same |
+ * | 32..63 | worse 1 byte |
+ * | 64..1048573 | same |
+ * | 1048576..2097151 | 1 byte better |
+ * | 2097152..134217727 | same |
+ * | 134217728..268435456 | 1 byte better |
  *
- *    type = 0:
- *          v0 is the resul 0..64 (or -32..32)
+ * etc.
  *
- *    type = 1:
- *          v0, v1 is the result, 14 bits
+ * ## Encoding format
  *
- *    type = 2:
- *          v0, v1, v2 are the result, 22bits
+ * Enncoded data could be 1 or more bytes in length. Data are
+ * packed as follows:
  *
- *    type = 3:
- *          v0, v1, v2, varint encoded
+ * | byte offset | bits range | field |
+ * |-------------|------------|-------|
+ * | 0 | 0..1 | type |
+ * | 0 | 2..7 | v0 |
+ * | 1 | 0..7 | v1 (when used) |
+ * | 2 | 0..7 | v2 (when used) |
  *
- *  Varint encodes bytes with last bit reserved as end
- *  flag and first 7 bits are data bits. Last bit 0 means end of the
- *  sequence.
+ * Then depending on the `type` field:
+ *
+ * | type | encoded |
+ * |------|---------|
+ * | 0 | v0 is the result 0..64 (or -32..32) |
+ * | 1 | v0 ## v1 are the result, 14 bits |
+ * | 2 | v0  ## v1 ## v2 are the result, 22bits
+ * | 3 | v0, ## v1 ## v2 ## (varint encoded rest) |
+ *
+ * Where `##` means bits concatenation. The bits are interpreted as BIG ENDIAN,
+ * for example `24573` will be encoded to `EA FF 02`
+ *
+ * See also [Varint] for its encoding description.
  *
  */
 object Smartint : IntCodec {