ircd::db: Additional comments and explanations.

include/ircd/db/cell.h

@@ -26,6 +26,17 @@
 namespace ircd {
 namespace db   {
 
+// A cell is a single key-value element existing within a column. This structure
+// provides the necessary facilities for working with a single cell. Many simple
+// operations can also be done through the column interface itself so check column.h
+// for satisfaction. Cells from different columns sharing the same key are composed
+// into a `row` (see: row.h).
+//
+// NOTE that this cell struct is type-agnostic. The database is capable of storing
+// binary data in the key or the value for a cell. The string_view will work with
+// both a normal string and binary data, so this class is not a template and offers
+// no conversions at this level. see: value.h/object.h
+//
 struct cell
 {
 	struct delta;
@@ -80,6 +91,11 @@ struct cell
 	friend std::ostream &operator<<(std::ostream &s, const cell &c);
 };
 
+//
+// A delta is an element of a database transaction. The cell::delta
+// is specific to a key in a column. Use cell deltas to make an
+// all-succeed-or-all-fail transaction across many cells in many columns.
+//
 struct cell::delta
 :std::tuple<op, cell &, string_view>
 {

include/ircd/db/column.h

@@ -46,7 +46,12 @@ namespace db   {
 // remove the IO/offload thread as well.
 //
 // [SET] usually occur without yielding your context because the DB is oriented
-// around write-log appending so it can deal with heavier tasks later in background.
+// around write-log appends. It deals with the heavier tasks later in background.
+//
+// NOTE that the column and cell structs are type-agnostic. The database is capable of
+// storing binary data in the key or the value for a cell. The string_view will work
+// with both a normal string and binary data, so this class is not a template and
+// offers no conversions at this level. see: value.h/object.h
 //
 struct column
 {
@@ -102,6 +107,12 @@ struct column
 	column() = default;
 };
 
+//
+// Delta is an element of a transaction. Use column::delta's to atomically
+// commit to multiple keys in the same column. Refer to delta.h for the `enum op`
+// choices. Refer to cell::delta to transact with multiple cells across
+// different columns.
+//
 struct column::delta
 :std::tuple<op, string_view, string_view>
 {
@@ -114,6 +125,12 @@ struct column::delta
 	{}
 };
 
+//
+// Iteration over all keys down a column. Default construction is an invalid
+// iterator, which could be compared against in the style of STL algorithms.
+// Otherwise, construct an iterator by having it returned from the appropriate
+// function in column::.
+//
 struct column::const_iterator
 {
 	using value_type = column::value_type;
@@ -159,8 +176,8 @@ struct column::const_iterator
 	friend void seek(column::const_iterator &, const string_view &key);
 };
 
-// Get property data of a db column.
-// R can optionally be uint64_t for some values.
+// Get property data of a db column. R can optionally be uint64_t for some
+// values. Refer to RocksDB documentation for more info.
 template<class R = std::string> R property(column &, const string_view &name);
 template<> std::string property(column &, const string_view &name);
 template<> uint64_t property(column &, const string_view &name);

include/ircd/db/delta.h

@@ -28,12 +28,12 @@ namespace db   {
 
 enum op
 {
-	GET,
-	SET,
-	MERGE,
-	DELETE,
-	DELETE_RANGE,
-	SINGLE_DELETE,
+	GET,                     // no-op sentinel, do not use (debug asserts)
+	SET,                     // (batch.Put)
+	MERGE,                   // (batch.Merge)
+	DELETE,                  // (batch.Delete)
+	DELETE_RANGE,            // (batch.DeleteRange)
+	SINGLE_DELETE,           // (batch.SingleDelete)
 };
 
 using merge_delta = std::pair<string_view, string_view>;

include/ircd/db/row.h

@@ -26,6 +26,9 @@
 namespace ircd {
 namespace db   {
 
+// A row is a collection of cells from different columns which all share the same
+// key. This is an interface for dealing with those cells in the aggregate.
+//
 struct row
 {
 	struct delta;