Add `EventHandlerResult::ABORT`

This will allow plugin handlers to send one of three different signals to the
calling hook functions, with three different interpretations:

`OK`: Continue calling the next handler.
`EVENT_CONSUMED`: Don't proceed to the next handler, but signal to the hook
  function's caller that an event was handled successfully.
`ABORT`: Stop processing, and signal to the hook function's caller that the
  event should be ignored.

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

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,
 };