doc(ByteBuffer-Serializer): Add javadocs and format description

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/BBType.java

@@ -4,7 +4,7 @@
 package org.terasology.persistence.typeHandling.bytebuffer;
 
 /**
- * Type codes for types.
+ * Type codes for array types.
  */
 public enum BBType {
     NULL(0),

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/ByteBufferPersistedData.java

@@ -12,23 +12,10 @@
 import java.nio.charset.StandardCharsets;
 
 /**
- * ByteBuffer-backed persisted data.
+ * ByteBuffer-backed persisted data representation.
  * <pre>
- *     Header:
- *     1 byte - header.
- *
- *     Types:
- *      NULL(0) - Null value
- *      BOOLEAN(1) - boolean - not packed. takes 1 byte.
- *      FLOAT(2)
- *      DOUBLE(3)
- *      LONG(4)
- *      INTEGER(5)
- *      STRING(6) - UTF-8. header: 1 int - length
- *      BYTES(7) - header: 1 int - length
- *      BYTEBUFFER(8) - just passthru this bytebuffer //TODO
- *      ARRAY(9) -
- *      VALUEMAP(10) -
+ * 1 byte - BBType
+ * 0..n bytes - data
  * </pre>
  */
 public class ByteBufferPersistedData implements PersistedData {

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/ByteBufferPersistedDataArray.java

@@ -21,6 +21,15 @@
 import java.util.List;
 import java.util.NoSuchElementException;
 
+/**
+ * ByteBuffer-backed persisted data array representation.
+ * <pre>
+ * 1 byte - BBType
+ * 1 byte - BBArrayType
+ * 4 bytes - size
+ * 0..n bytes - data
+ * </pre>
+ */
 public class ByteBufferPersistedDataArray extends ByteBufferPersistedData implements PersistedDataArray {
 
     private final BBArrayType arrayType;

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/ByteBufferPersistedDataMap.java

@@ -12,6 +12,17 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * ByteBuffer-backed persisted data map representation.
+ * <pre>
+ *     1 byte -  type = 10
+ *     4 byte - size
+ *     8 * size bytes - refmap
+ *     0..n bytes - key and value data.
+ * </pre>
+ * <p>
+ * Use refmap - links to key and value positions. provide almost constant read time.
+ */
 public class ByteBufferPersistedDataMap extends ByteBufferPersistedData implements PersistedDataMap {
 
     public ByteBufferPersistedDataMap(ByteBuffer byteBuffer) {

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/ByteBufferPersistedSerializer.java

@@ -25,7 +25,7 @@
 
 
 /**
- * TODO make direct serializer factory.
+ * Provide possible serialize data to ByteBuffer.
  */
 public class ByteBufferPersistedSerializer implements PersistedDataSerializer {
 

subsystems/TypeHandlerLibrary/src/main/java/org/terasology/persistence/typeHandling/bytebuffer/package-info.java

@@ -0,0 +1,53 @@
+// Copyright 2021 The Terasology Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * ByteBuffer serializer provide possible to read and write bytebuffer directly.
+ * <p>
+ * <pre>
+ *         Format:
+ *         Types(BBType):
+ *            NULL(0) - size = 1 byte, format = type(byte value = 0)
+ *            BOOLEAN(1) - size = 2 bytes, format = type(byte value = 1) + value(1 byte). ( yeah a bit not optimal)
+ *            FLOAT(2) - size = 5 bytes, format = type(byte value = 2) + value(1 float = 4 bytes)
+ *            DOUBLE(3) - size = 9 bytes, format = type(byte value = 3) + value(1 double = 8 bytes)
+ *            LONG(4) -  size = 9 bytes, format = type(byte value = 4) + value(1 long = 8 bytes)
+ *            INTEGER(5) - size = 5 bytes, format = type(byte value = 5) + value(1 int = 4 bytes)
+ *            STRING(6) - size = 5..n bytes, format =  type(byte value = 6) + size(1 int = 4 bytes) + value($size bytes)
+ *            BYTES(7) - size = 5..n bytes, format =  type(byte value = 7) + size(1 int = 4 bytes) + value($size bytes)
+ *            BYTEBUFFER(8) - size = 5..n bytes, format =  type(byte value = 8) + size(1 int = 4 bytes) + value($size bytes)
+ *            ARRAY(9) -
+ *                  size = 6..n bytes.
+ *                  format = type(byte value = 9) + data(see ArrayTypes)
+ *            VALUEMAP(10) -
+ *                  size = 5..n bytes.
+ *                  format =  type(byte value = 10) +
+ *                            size(1 int = 4 bytes) +
+ *                            refmap(format = (keyRef(1 int) + valueRef(1 int)) * $size) +
+ *                            keydata(format = (STRING(6) - 1 byte($STRING.type) * $size ) +
+ *                            valuedata(format = (any BBType) * $size)
+ *
+ *         ArrayTypes(BBArrayType):
+ *            BOOLEAN(0) - size = 5..n bytes.
+ *                       format = arraytype(byte value = 0) + size(1 int = 4 bytes) + data(($size % 8 + 1) bytes)
+ *            FLOAT(1) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 1) + size(1 int = 4 bytes) + data($size floats = $size * 4 bytes)
+ *            DOUBLE(2) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 2) + size(1 int = 4 bytes) + data($size double = $size * 8 bytes)
+ *            LONG(3) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 3) + size(1 int = 4 bytes) + data($size longs = $size * 8 bytes)
+ *            INTEGER(4) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 4) + size(1 int = 4 bytes) + data($size ints = $size * 4 bytes)
+ *            STRING(5) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 5) +
+ *                                size(1 int = 4 bytes) +
+ *                                sizeArray(format = STRING(6).size = 1 int * $size = 4 byte * $size) +
+ *                                stringdata(format = (STRING(6) - 1 byte($STRING.type)) * $size)
+ *            VALUE(6) - size = 5 .. n bytes.
+ *                       format = arraytype(byte value = 5) +
+ *                                size(1 int = 4 bytes) +
+ *                                sizeArray(format = (any BBType whole size) = 1 int * $size = 4 byte * $size) +
+ *                                stringdata(format = (any BBType) * $size)
+ *     </pre>
+ */
+package org.terasology.persistence.typeHandling.bytebuffer;