From 7022e6f268d0fc4c4cbd33b5f460a38b25173544 Mon Sep 17 00:00:00 2001
From: Pietro Gagliardi <pietro10@mac.com>
Date: Mon, 13 May 2019 06:37:19 -0400
Subject: [PATCH] More programmer error refinement.

---
 common/programmererror.c |  2 ++
 common/uipriv.h          |  4 ++++
 doc/events.md            | 24 ++++++++++++++++++------
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/common/programmererror.c b/common/programmererror.c
index 3f68a8d2..05bb7415 100644
--- a/common/programmererror.c
+++ b/common/programmererror.c
@@ -7,6 +7,8 @@
 static const char *messages[] = {
 	[uiprivProgrammerErrorWrongStructSize] = "wrong size %zu for %s",
 	[uiprivProgrammerErrorIndexOutOfRange] = "index %d out of range in %s()",
+	[uiprivProgrammerErrorNullPointer] = "invalid null pointer for %s passed into %s()",
+	[uiprivProgrammerErrorIntIDNotFound] = "%s identifier %d not found in %s()",
 };
 
 static void prepareProgrammerError(char *buf, int size, unsigned int which, va_list ap)
diff --git a/common/uipriv.h b/common/uipriv.h
index 86890f60..aadcafbd 100644
--- a/common/uipriv.h
+++ b/common/uipriv.h
@@ -14,6 +14,10 @@ extern int uiprivInitReturnErrorf(uiInitError *err, const char *msg, ...);
 enum {
 	uiprivProgrammerErrorWrongStructSize,		// arguments: size_t badSize, const char *structName
 	uiprivProgrammerErrorIndexOutOfRange,	// arguments: int badIndex, __func__
+	uiprivProgrammerErrorNullPointer,			// arguments: const char *paramDesc, __func__
+	uiprivProgrammerErrorIntIDNotFound,		// arguments: const char *idDesc, int badID, __func__
+	// TODO type mismatch
+	// TODO attempt to change event during uiEventFire()
 	uiprivNumProgrammerErrors,
 };
 extern void uiprivProgrammerError(unsigned int which, ...);
diff --git a/doc/events.md b/doc/events.md
index d48031de..bfbb4587 100644
--- a/doc/events.md
+++ b/doc/events.md
@@ -46,7 +46,9 @@ If `Global` is true, the event is "global" — there are no specific senders, an
 uiEvent *uiNewEvent(uiEventOptions *options);
 ```
 
-`uiNewEvent()` creates a new `uiEvent`.
+`uiNewEvent()` creates a new `uiEvent` with the given options.
+
+It is a programmer error to specify `NULL` for `options`.
 
 ### `uiEventAddHandler()`
 
@@ -62,12 +64,16 @@ The return value is an identifier that may be used to delete or block the event.
 
 Note that event handlers are NOT deduplicated; if you call `uiEventAddHandler()` twice with the same `handler`, then `handler` will be registered twice and will thus be called twice, even if `sender` and/or `data` are the same, and `uiEventAddHandler()` will return two distinct identifiers.
 
+It is a programmer error to specify `NULL` for `e` or `handler`.
+
 ### `uiEventDeleteHandler()`
 
 ```c
-void uiEventDeleteHandler(uiEvent *e, int which);
+void uiEventDeleteHandler(uiEvent *e, int id);
 ```
 
+It is a programmer error to specify `NULL` for `e` or a currently unregistered value for `id`.
+
 ### `uiEventFire()`
 
 ```c
@@ -82,20 +88,26 @@ Each handler that is to be called will receive whatever you pass in as `args` to
 
 Note that the order that handler functions are called in is unspecified.
 
+It is a programmer error to specify `NULL` for `e`.
+
 ### `uiEventHandlerBlocked()`
 
 ```c
-bool uiEventHandlerBlocked(uiEvent *e, int which);
+bool uiEventHandlerBlocked(uiEvent *e, int id);
 ```
 
-`uiEventHandlerBlocked()` returns whether or not the given registered event handler is *blocked*. A blocked event handler will not be called by `uiEventFire()`, even if that handler matches the parameters passed to `uiEventFire()`. `which` should be the identifier of a previously registered event handler as returned by `uiEventAddHandler()`.
+`uiEventHandlerBlocked()` returns whether or not the given registered event handler is *blocked*. A blocked event handler will not be called by `uiEventFire()`, even if that handler matches the parameters passed to `uiEventFire()`. `id` should be the identifier of a previously registered event handler as returned by `uiEventAddHandler()`.
+
+It is a programmer error to specify `NULL` for `e` or a currently unregistered event identifier for `id`.
 
 ### `uiEventSetHandlerBlocked()`
 
 ```c
-void uiEventSetHandlerBlocked(uiEvent *e, int which, bool blocked);
+void uiEventSetHandlerBlocked(uiEvent *e, int id, bool blocked);
 ```
 
-`uiEventSetHandlerBlocked()` changes whether or not the given registered event handler is bocked. `which` should be the identifier of a previously registered event handler as returned by `uiEventAddHandler()`.
+`uiEventSetHandlerBlocked()` changes whether or not the given registered event handler is bocked. `id` should be the identifier of a previously registered event handler as returned by `uiEventAddHandler()`.
 
 The effect of calling this function on a handler that matches a currently active `uiEventFire()` is unspecified.
+
+It is a programmer error to specify `NULL` for `e` or a currently unregistered event identifier for `id`.