diff --git a/include/ircd/ios/descriptor.h b/include/ircd/ios/descriptor.h
index 4e9f26631..dbbde70a1 100644
--- a/include/ircd/ios/descriptor.h
+++ b/include/ircd/ios/descriptor.h
@@ -19,6 +19,9 @@ namespace ircd::ios
 	const string_view &name(const descriptor &);
 }
 
+/// Each descriptor classifies and quantifies our operations through asio.
+/// Instances are usually static; all callback handlers are wrapped with an
+/// ios::handle and associated with an ios::descriptor instance.
 struct ircd::ios::descriptor
 :instance_list<descriptor>
 {
@@ -48,6 +51,7 @@ struct ircd::ios::descriptor
 	~descriptor() noexcept;
 };
 
+/// Statistics for the descriptor.
 struct ircd::ios::descriptor::stats
 {
 	using value_type = uint64_t;
diff --git a/include/ircd/ios/handler.h b/include/ircd/ios/handler.h
index 1316919e0..a788337e6 100644
--- a/include/ircd/ios/handler.h
+++ b/include/ircd/ios/handler.h
@@ -21,6 +21,8 @@ namespace ircd::ios
 	const string_view &name(const handler &);
 }
 
+/// Non-template base class for ios::handle; templated derivations of this
+/// class comprise the function object we're submitting to boost::asio.
 struct ircd::ios::handler
 {
 	static thread_local handler *current;
@@ -38,6 +40,9 @@ struct ircd::ios::handler
 	uint64_t ts {0}; // last tsc sample; for profiling each phase
 };
 
+/// Our function object type template. These should be rvalue-constructed in a
+/// callback argument to a boost::asio call. A reference to an ios::descriptor
+/// must be provided.
 template<class function>
 struct ircd::ios::handle
 :handler
@@ -54,6 +59,9 @@ struct ircd::ios::handle
 // ircd::ios::handle
 //
 
+/// Construction of the handle is considered the enquement. Construct in the
+/// callback argument to a boost::asio call; provide a reference to the
+/// appropriate callsite descriptor.
 template<class function>
 inline
 ircd::ios::handle<function>::handle(ios::descriptor &d,