Documentation goes brrrrr

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
 

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

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