From c25423b94cfa850359fc7b175b9b6f21a1a843c2 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 4 Oct 2024 16:19:19 -0400
Subject: [PATCH] docs: Filled in some category pages.
---
include/SDL3/SDL_error.h | 20 ++++++++++++++++++++
include/SDL3/SDL_hints.h | 2 --
include/SDL3/SDL_init.h | 24 ++++++++++++++++++++++--
include/SDL3/SDL_video.h | 22 +++++++++++++++++++++-
4 files changed, 63 insertions(+), 5 deletions(-)
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index ed79fc2dd051e..5adf4807dccaf 100644
--- a/include/SDL3/SDL_error.h
+++ b/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_
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 23e051974d397..4550090a16955 100644
--- a/include/SDL3/SDL_hints.h
+++ b/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.
*
diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h
index 9029734339258..327710dd2e4de 100644
--- a/include/SDL3/SDL_init.h
+++ b/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_
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 6c85ed325006e..176543abbb366 100644
--- a/include/SDL3/SDL_video.h
+++ b/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_