BTreeDB6 format specs

src/main/kotlin/ru/dbotthepony/kommons/io/BTreeDB6.kt

@@ -55,6 +55,18 @@ private fun readHeader(reader: RandomAccessFile, required: Char) {
  * common ForkJoinPool is meant ot be used by calculation-intense operations. [BTreeDB6] is, on the other hand,
  * is I/O intense, and can stall executor threads. A good Executor here would be one that can spawn a lot of threads,
  * for example, [java.util.concurrent.Executors.newCachedThreadPool].
+ *
+ * Format specs:
+ * * Block size can be anything between 64 and 2^31 - 1 bytes. Creation through [create] restricts block size to 128 and up, since that's
+ * already absurdly small block size!
+ * * Blocks are addressed by 32-bit integer. Due to Java int being signed, this allows to address at most 2^31 - 1 blocks.
+ * With block size of 4096 bytes, this puts max filesize just a little below 8 TiB. Merely opening such large file will require
+ * 255 MiB of RAM (to hold free bitmap).
+ * * Free space is stored as bitmap. As such, smaller blocks require more space for storing free bitmap, and hence will take more
+ * time during writes
+ * * All write operations are done in new blocks, outdated blocks erased with zeroes only when header updated to point
+ * at new tree
+ * * Keys can freely vary in size inside single DB, keys can be up to 2^31 - 1 bytes in size
  */
 // TODO: Checksums (TREE/LEAF/DATA)
 // TODO: Second tree (TREE/LEAF redundancy)