From 78d6db2cc4b32b7af24dd0d841db4ed600daa398 Mon Sep 17 00:00:00 2001
From: Philippe PITTOLI <karchnu@karchnu.fr>
Date: Mon, 20 May 2024 13:38:58 +0200
Subject: [PATCH] Documentation goes brrrrr

---
 src/dodb/exceptions.cr |  9 ++++++++-
 src/dodb/indexer.cr    | 23 ++++++++++++++++++-----
 src/dodb/no_index.cr   |  5 ++++-
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/src/dodb/exceptions.cr b/src/dodb/exceptions.cr
index d41bb9f..a2c9c37 100644
--- a/src/dodb/exceptions.cr
+++ b/src/dodb/exceptions.cr
@@ -1,17 +1,24 @@
-
+# Exception `DODB::MissingEntry` is thrown anytime the database
+# tries to retrieve a value with an invalid key.
 class DODB::MissingEntry < Exception
 	getter index : String?
 	getter key   : String | Int32
 
+	# The exception will contain both the key and the name of the index,
+	# and a human-readable string.
 	def initialize(@index, @key)
 		super "no entry in index '#{@index}' for key '#{@key}'"
 	end
 
+	# The exception will contain the key and a human-readable string.
 	def initialize(@key)
 		super "no entry for key '#{@key}' in database"
 	end
 end
 
+# Exception `DODB::IndexOverload` is thrown anytime there is a
+# collision with an index. This is currently only used by `DODB::Index`
+# since other indexes don't have collisions.
 class DODB::IndexOverload < Exception
 end
 
diff --git a/src/dodb/indexer.cr b/src/dodb/indexer.cr
index 089982e..2d821e3 100644
--- a/src/dodb/indexer.cr
+++ b/src/dodb/indexer.cr
@@ -1,12 +1,25 @@
-
+# Abstract class `DODB::Indexer(V)` represents the specifications for
+# the indexes (basic indexes, partitions, tags, etc.).
 abstract class DODB::Indexer(V)
-	abstract def index   (key : String, value : V)
-	abstract def deindex (key : String, value : V)
-	abstract def check!  (key : String, value : V, old_value : V?)
-	abstract def name                : String
 
+	# Indexes a value.
+	abstract def index   (key : String, value : V)
+
+	# Removes the index of a value.
+	abstract def deindex (key : String, value : V)
+
+	# Verifies whether a new value will create a collision with the index of currently stored value.
+	abstract def check!  (key : String, value : V, old_value : V?)
+
+	# Name of the index, such as *id* or *color* for example.
+	# This is an arbitrary value, mostly to create the index directory.
+	abstract def name               : String
+
+	# Directory where the values will be written.
 	abstract def indexing_directory : String
 
+	# Removes all the index entries.
+	# By default, removes the `#indexing_directory`.
 	def nuke_index
 		FileUtils.rm_rf indexing_directory
 	end
diff --git a/src/dodb/no_index.cr b/src/dodb/no_index.cr
index 7b4a0a7..8c0d929 100644
--- a/src/dodb/no_index.cr
+++ b/src/dodb/no_index.cr
@@ -1,4 +1,4 @@
-
+# In case a value doesn't have the attribute to be indexed.
 class DODB::NoIndex
 	include JSON::Serializable
 
@@ -9,6 +9,9 @@ class DODB::NoIndex
 end
 
 module DODB
+	# Since the `NoIndex` class doesn't convey any value,
+	# there is no point creating multiple instances.
+	# Use `DODB#no_index` any time a `NoIndex` instance is required.
 	class_getter no_index = NoIndex.new
 end