docs: Filled in some category pages.

include/SDL3/SDL_error.h

@@ -23,6 +23,26 @@
  * # CategoryError
  *
  * Simple error message routines for SDL.
+ *
+ * Most apps will interface with these APIs in exactly one function: when
+ * almost any SDL function call reports failure, you can get a human-readable
+ * string of the problem from SDL_GetError().
+ *
+ * These strings are maintained per-thread, and apps are welcome to set their
+ * own errors, which is popular when building libraries on top of SDL for
+ * other apps to consume. These strings are set by calling SDL_SetError.
+ *
+ * A common usage pattern is to have a function that returns true for success
+ * and false for failure, and do this when something fails:
+ *
+ * ```c
+ * if (something_went_wrong) {
+ *    return SDL_SetError("The thing broke in this specific way: %d", errcode);
+ * }
+ * ```
+ *
+ * It's also common to just return `false` in this case if the failing thing
+ * is known to call SDL_SetError(), so errors simply propagate through.
  */
 
 #ifndef SDL_error_h_

include/SDL3/SDL_hints.h

@@ -22,8 +22,6 @@
 /**
  * # CategoryHints
  *
- * Official documentation for SDL configuration variables
- *
  * This file contains functions to set and get configuration hints, as well as
  * listing each of them alphabetically.
  *

include/SDL3/SDL_init.h

@@ -22,10 +22,30 @@
 /**
  * # CategoryInit
  *
- * SDL subsystem init and quit functions.
+ * All SDL programs need to initialize the library before starting to work
+ * with it.
+ *
+ * Almost everything can simply call SDL_Init() near startup, with a handful
+ * of flags to specify subsystems to touch. These are here to make sure SDL
+ * does not even attempt to touch low-level pieces of the operating system
+ * that you don't intend to use. For example, you might be using SDL for
+ * video and input but chose an external library for audio, and in this case
+ * you would just need to leave off the `SDL_INIT_AUDIO` flag to make sure
+ * that external library has complete control.
+ *
+ * Most apps, when terminating, should call SDL_Quit(). This will clean up
+ * (nearly) everything that SDL might have allocated, and crucially, it'll
+ * make sure that the display's resolution is back to what the user expects
+ * if you had previously changed it for your game.
+ *
+ * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata at startup
+ * to fill in details about the program. This is completely optional, but it
+ * helps in small ways (we can provide an About dialog box for the macOS menu,
+ * we can name the app in the system's audio mixer, etc). Those that want to
+ * provide a _lot_ of information should look at the more-detailed
+ * SDL_SetAppMetadataProperty().
  */
 
-
 #ifndef SDL_init_h_
 #define SDL_init_h_
 

include/SDL3/SDL_video.h

@@ -22,7 +22,27 @@
 /**
  * # CategoryVideo
  *
- * SDL video functions.
+ * SDL's video subsystem is largely interested in abstracting window
+ * management from the underlying operating system. You can create windows,
+ * manage them in various ways, set them fullscreen, and get events when
+ * interesting things happen with them, such as the mouse or keyboard
+ * interacting with a window.
+ *
+ * The video subsystem is also interested in abstracting away some
+ * platform-specific differences in OpenGL: context creation, swapping buffers,
+ * etc. This may be crucial to your app, but also you are not required to use
+ * OpenGL at all.
+ * In fact, SDL can provide rendering to those windows as well, either with an
+ * easy-to-use [2D API](https://wiki.libsdl.org/SDL3/CategoryRender)
+ * or with a more-powerful [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU).
+ * Of course, it can simply get out of your way and give you the window
+ * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like
+ * directly, too.
+ *
+ * The video subsystem covers a lot of functionality, out of necessity, so it
+ * is worth perusing the list of functions just to see what's available, but
+ * most apps can get by with simply creating a window and listening for
+ * events, so start with SDL_CreateWindow() and SDL_PollEvent().
  */
 
 #ifndef SDL_video_h_