Fleshed out init-main.md some more.

doc/init-main.md

@@ -2,17 +2,17 @@
 
 # Initialization and the Main Loop
 
-## Initialization
+## Overview
 
-In order to use libui, you must first initialize it. All initialization is done through the `uiInit()` function. 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.
+In order to use libui, you must first initialize it. All initialization is done through the `uiInit()` function. This is usually one of the first things you do in your program.
+
+The thread you call `uiInit()` on becomes the "GUI thread". This is the thread that all your UI is done on from the perspective of the operating system, so it is absolutely essential that you do **not** call any other function of libui from any other thread that you create (except for `uiQueueMain()`, which is discussed later).
 
 Furthermore, on some systems, this thread must also be the thread that `main()` is called on; macOS is the notable example here. Therefore, to be safe, you should only call `uiInit()` from `main()`, or from a function that runs on the same thread as `main()`. If you are using a language binding, that binding may provide further instruction on how to do so in that language.
 
-`uiInit()` takes a set of options for setting up libui at a low level. There are no options at present, so this must currently be `NULL`.
+`uiInit()` *can* fail, in which case it will provide information about that failure in a special variable of type `uiInitError` that you provide it. The most useful member of this struct is `Message`, which contains a human-readable error message you can use to diagnose problems initializing libui. If you are using a language binding, the language binding may abstract this away and provide the error to you in a langauge-specific form.
 
-`uiInit()` *can* fail, in which case libui is not safe to use. `uiInit()` will return a human-readable error message to the caller if it does fail. You are also responsible for both allocating and initializing the memory for this error message, since part of libui's initialization includes initialization of its memory allocators. The reference entry below has more information.
-
-Here is an example of correct use of `uiInit()`:
+Here is an example of correct use of `uiInit()` in C:
 
 ```c
 uiInitError err;
@@ -35,6 +35,18 @@ Note that if `uiInit()` fails, you **cannot** use libui's message box functions
 int uiInit(void *options, uiInitError *err);
 ```
 
+`uiInit()` initializes libui. It returns nonzero on success and zero 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 zero without doing anything. 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.
+
+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.
+
+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.
+
+**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.
+
 ### `uiUninit()`
 
 ```c