diff --git a/include/ircd/m/event/prev.h b/include/ircd/m/event/prev.h
index 51c0a91dd..22ad1f7aa 100644
--- a/include/ircd/m/event/prev.h
+++ b/include/ircd/m/event/prev.h
@@ -25,6 +25,15 @@ namespace ircd::m
 	std::string pretty_oneline(const event::prev &);
 }
 
+/// Interface to the previous-references of an event. This interface overlays
+/// on the m::event tuple and adds functionality focused specifically on the
+/// various reference properties in the event data.
+///
+/// Instances of this class "overlay" on the event tuple, meaning one just
+/// passes an m::event (or a json::object which would be passed to an m::event)
+/// to the constructor of this class. This class only has the properties of
+/// the event which contain references, and a suite of functions to work with
+/// those references.
 struct ircd::m::event::prev
 :json::tuple
 <
diff --git a/include/ircd/m/event/refs.h b/include/ircd/m/event/refs.h
index 5b63ccb1d..e6be9e649 100644
--- a/include/ircd/m/event/refs.h
+++ b/include/ircd/m/event/refs.h
@@ -16,6 +16,11 @@ namespace ircd::m::dbs
 	enum class ref :uint8_t;
 }
 
+/// Interface to the forward-references for an event. Forward-references are
+/// virtually constructed from prev-references made by other events. This
+/// interface queries the database which has pre-indexed the prev-references
+/// made by other events at their insertion (it does not conduct any expensive
+/// scan when using this interface, etc).
 struct ircd::m::event::refs
 {
 	event::idx idx;