Documentation about partitions.

src/dodb/index.cr

@@ -288,6 +288,7 @@ end
 #
 # NOTE: cached, reasonable amount of memory used since it's just an index.
 # NOTE: fast for retrieval, slow for index creation and deletion (fs operations).
+# NOTE: see `Index` for an uncached version, even less memory-hungry.
 # NOTE: for fast operations without fs representation, see `RAMOnlyIndex`.
 class DODB::CachedIndex(V) < DODB::Index(V)
 	# This hash contains the relation between the index key and the data key.

src/dodb/partition.cr

@@ -2,6 +2,31 @@ require "file_utils"
 
 require "./indexer.cr"
 
+# Partitions for 1-to-n relations.
+# Uncached version.
+#
+# This (partition) index provides a file-system representation, enabling the administrators to
+# select a value based on its index. The following example presents an index named "color"
+# with some data indexed by a color attribute.
+#
+# ```plain
+# storage
+# ├── data
+# │   ├── 0000000000
+# │   ├── 0000000001
+# │   └── 0000000002
+# ├── partitions
+# │   └── by_color  <- this is an example of index named "color"
+# │       ├── red
+# │       │   └── 0000000000 -> ../../data/0000000000
+# │       └── blue
+# │           ├── 0000000001 -> ../../data/0000000001
+# │           └── 0000000002 -> ../../data/0000000002
+# ```
+#
+# NOTE: no cache, thus considered as *slow* for creation, deletion **and retrieval**.
+# NOTE: see `CachedPartition` for a cached version, faster for retrieval.
+# NOTE: for fast operations without fs representation, see `RAMOnlyPartition`.
 class DODB::Partition(V) < DODB::Indexer(V)
 	property name         : String
 	property key_proc     : Proc(V, String | NoIndex) | Proc(V, String)
@@ -100,6 +125,32 @@ class DODB::Partition(V) < DODB::Indexer(V)
 	end
 end
 
+# Partitions for 1-to-n relations.
+# Cached version.
+#
+# This (partition) index provides a file-system representation, enabling the administrators to
+# select a value based on its index. The following example presents an index named "color"
+# with some data indexed by a color attribute.
+#
+# ```plain
+# storage
+# ├── data
+# │   ├── 0000000000
+# │   ├── 0000000001
+# │   └── 0000000002
+# ├── partitions
+# │   └── by_color  <- this is an example of index named "color"
+# │       ├── red
+# │       │   └── 0000000000 -> ../../data/0000000000
+# │       └── blue
+# │           ├── 0000000001 -> ../../data/0000000001
+# │           └── 0000000002 -> ../../data/0000000002
+# ```
+#
+# NOTE: cached, reasonable amount of memory used since it's just an index.
+# NOTE: fast for retrieval, slow for index creation and deletion (fs operations).
+# NOTE: see `Partition` for an uncached version, even less memory-hungry.
+# NOTE: for fast operations without fs representation, see `RAMOnlyPartition`.
 class DODB::CachedPartition(V) < DODB::Partition(V)
 	# This hash contains the relation between the index key and the data keys.
 	property data = Hash(String, Array(Int32)).new
@@ -173,9 +224,17 @@ class DODB::CachedPartition(V) < DODB::Partition(V)
 	end
 end
 
+# Partitions for 1-to-n relations.
+# RAM-only version.
+#
+# Since there is no file-system operations, all the operations are fast.
 # `DODB::RAMOnlyPartition` enables the flexibility of partitions without a file-system representation.
 # Absolute efficiency, exactly as easy to use as the other partition implementations.
-
+#
+# NOTE: reasonable amount of memory used since it's just an index.
+# NOTE: fast for all operations, but no file-system representation.
+# NOTE: see `Partition` for an uncached version, even less memory-hungry.
+# NOTE: for an fs representation but still fast for retrieval, see `CachedPartition`.
 class DODB::RAMOnlyPartition(V) < DODB::CachedPartition(V)
 	def index(key, value)
 		partition = key_proc.call value