diff --git a/src/kaleidoscope/event_handler_result.h b/src/kaleidoscope/event_handler_result.h
index 9b5d6caf..f22bffee 100644
--- a/src/kaleidoscope/event_handler_result.h
+++ b/src/kaleidoscope/event_handler_result.h
@@ -18,9 +18,33 @@
 
 namespace kaleidoscope {
 
+// This is the set of return values for event handlers. Event handlers for
+// plugins are called in sequence by the corresponding hook function, in plugin
+// initialization order. The interpretation of these return values can vary
+// based on the needs of the hook function, but should be as follows:
+//
+// - OK: Continue processing the event. The calling hook function should
+//       continue calling next event handler in the sequence. If all event
+//       handlers return `OK`, finish processing the event.
+//
+// - EVENT_CONSUMED: Stop processing event handlers. The calling hook function
+//       should not call any further handlers, but may continue to take some
+//       actions to finish processing the event. This should be used to indicate
+//       that the event has been successfully handled.
+//
+// - ABORT: Ignore the event. The calling hook function should not call any
+//       further handlers, and should treat the event as if it didn't
+//       happen. This should be used by plugin handlers that need to either
+//       suppress an event or queue the event in order to delay it.
+//
+// - ERROR: Undefined error. The calling hook function should not call any
+//       further handlers. There is currently no specification for what should
+//       happen if this is returned.
+
 enum class EventHandlerResult {
   OK,
   EVENT_CONSUMED,
+  ABORT,
   ERROR,
 };