More programmer error refinement.

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)

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, ...);

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`.