Made uiInit() programmer errors actual programmer errors and not normal error returns. This makes the error handling, the documentation, and even the tests much easier, and also makes programmer error handling more consistent. Also defined programmer error cases for uiMain() and uiQuit(). We'll implement all of these next.

doc/init-main.md

@@ -16,13 +16,15 @@ bool uiInit(void *options, uiInitError *err);
 
 `uiInit()` initializes libui. It returns `true` on success and `false` on failure; in the event of a failure, `err` is filled with relevant information explaining the failure.
 
-`err` is required and must be properly initialized. If `err` is `NULL` or `err->Size` does not match `sizeof (uiError)`, `uiInit()` immediately returns `false` without doing anything. If any of the other fields of `err` are not zero-initialized as with `memset(0)`, the behavior is undefined.
+`err` is required and must be properly initialized. It is a programmer error for `err` to be `NULL` or for `err->Size` to not match `sizeof (uiError)`, `uiInit()`. If any of the other fields of `err` are not zero-initialized as with `memset(0)`, the behavior is undefined.
 
-`options` must be `NULL`; no options are currently defined. If `options` is not `NULL`, `uiInit()` will return an error without initializing anything.
+`options` must be `NULL`; no options are currently defined. It is a programmer error for `options` to not be `NULL`.
 
-As part of initialization, the thread that `uiInit()` is called on becomes the GUI thread. All of the functions of libui except `uiQueueMain()` **must** be called from this thread. On platforms where which thread you run GUI code on is restricted, `uiMain()` will return an error if it is called from the wrong thread; to avoid this, you should always call `uiInit()` from the thread that `main()` itself is called from.
+It is a programmer error to call `uiInit()` more than once, even if `uiMain()` has already returned (meaning you cannot re-initialize libui). It is a programmer error to call libui functions before `uiInit()` has been called.
 
-If `uiInit()` fails, no other libui function is safe to call. This means that you cannot use any of libui's message box functions to report the error.
+As part of initialization, the thread that `uiInit()` is called on becomes the GUI thread. All of the functions of libui except `uiQueueMain()` **must** be called from this thread. On platforms where which thread you run GUI code on is restricted, libui will behave in an undefined way if it is called from the wrong thread; to avoid this, you should always call `uiInit()` (and by extension all libui functions) from the thread that `main()` itself is called from.
+
+If `uiInit()` fails, it will be a programmer error to call any other libui function. This means that you cannot use any of libui's message box functions to report the error.
 
 **Notes for language binding authors**: Your language will likely provide its own preferred mechanism for reporting errors. You should wrap `uiInit()` to return errors this way, creating and managing the memory for `uiInitError` yourself and transforming the returned error according to both the format of `uiInitError` described below and the rules for encoding errors in your language of choice.
 
@@ -50,7 +52,7 @@ void uiMain(void);
 
 `uiMain()` runs the main event loop. It does not return until `uiQuit()` is called.
 
-TODO make it illegal to call more than once?
+It is a programmer error to call `uiMain()` more than once.
 
 ### `uiQuit()`
 
@@ -60,9 +62,7 @@ void uiQuit(void);
 
 `uiQuit()` causes `uiMain()` to return once the current event has finished processing.
 
-TODO safety of calling `uiMain()` again after `uiQuit()`?
-
-TODO behavior of calling `uiQuit()` outside of a `uiMain()` (before, after, etc.)
+It is an error to call `uiQuit()` before `uiMain()` is called or after `uiMain()` returns. It is a programmer error to call `uiQuit()` more than once.
 
 ### `uiQueueMain()`
 
@@ -75,3 +75,5 @@ void uiQueueMain(void (*f)(void *data), void *data);
 `uiQueueMain()` can safely be called from any thread, not just the UI thread.
 
 If you call `uiQueueMain()` in sequence, the functions will execute in that order; if other threads are calling `uiQueueMain()` at the same time, there is no guarantee as to whether the calls are interleaved, but the order per-thread will be maintained.
+
+If `uiQuit()` is called, it is undefined whether any still-queued functions will be called.