ircd::db: Update docs.

include/ircd/db/cell.h

@@ -116,8 +116,7 @@ namespace ircd::db
 {
 	// [SET] Perform operations in a sequence as a single transaction. No template
 	// iterators supported yet, just a ptr range good for contiguous sequences like
-	// vectors and initializer_lists. To support any iterator I think we'll need to
-	// forward-expose a wrapping of rocksdb::WriteBatch.
+	// vectors and initializer_lists. Alternatively, see: iov.h.
 	void write(const cell::delta *const &begin, const cell::delta *const &end, const sopts & = {});
 	void write(const std::initializer_list<cell::delta> &, const sopts & = {});
 	void write(const sopts &, const std::initializer_list<cell::delta> &);

include/ircd/db/index.h

@@ -28,6 +28,26 @@ namespace ircd::db
 	struct index;
 }
 
+/// An index is a glorified column; the database descriptor for this column
+/// must specify a prefix-extractor otherwise this index just behaves like
+/// a regular key/value column. Index is used to create iterable domains of
+/// a column which all share the same key-prefix.
+///
+/// The index allows a concatenation of two strings to form a key. This con-
+/// catenated key is still unique for the column as a whole and is stored as
+/// the full concatenation -- however, as stated above the prefix function must
+/// be aware of how such a concatenation can be separated back into two
+/// strings.
+///
+/// db::index allows the user to query for either just the first string, or
+/// the whole concatenation. In either case, the resulting iterator can move
+/// only around the keys and values within the domain of that first string.
+/// The iterator presents the user with it.first = second string only, thereby
+/// hiding the prefix allowing for easier iteration of the domain.
+///
+/// Index is not good at reverse iteration due to limitations in RocksDB. Thus
+/// it's better to just flip the comparator function for the column.
+///
 struct ircd::db::index
 :column
 {

ircd/db.cc

@@ -1310,6 +1310,9 @@ ircd::db::for_each(const iov &t,
 	wb.Iterate(&h);
 }
 
+/// Iterate the iov using the "until protocol"
+/// reminder: the closure remains-true-until-the-end; false to break;
+/// returns true if the end reached; false if broken early
 bool
 ircd::db::until(const iov &t,
                 const std::function<bool (const delta &)> &closure)