SDL: include: Filling in more documentation gaps.

From a790a678836afa4f954d75584219c06789b961d8 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 3 May 2024 13:01:41 -0400
Subject: [PATCH] include: Filling in more documentation gaps.

---
 include/SDL3/SDL_audio.h   |   1 -
 include/SDL3/SDL_cpuinfo.h |  12 ++--
 include/SDL3/SDL_surface.h |  14 ++++-
 include/SDL3/SDL_system.h  | 110 +++++++++++++++++++++++++++++++------
 include/SDL3/SDL_video.h   |  27 ++++-----
 5 files changed, 126 insertions(+), 38 deletions(-)

diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index e6ae924bcf931..08a1b7c149eb8 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -312,7 +312,6 @@ typedef struct SDL_AudioSpec
  *
  * \sa SDL_CreateAudioStream
  */
-struct SDL_AudioStream;  /**< this is opaque to the outside world. */
 typedef struct SDL_AudioStream SDL_AudioStream;
 
 
diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h
index 59a4b325392e6..8c077299d6581 100644
--- a/include/SDL3/SDL_cpuinfo.h
+++ b/include/SDL3/SDL_cpuinfo.h
@@ -36,10 +36,14 @@
 extern "C" {
 #endif
 
-/* This is a guess for the cacheline size used for padding.
- * Most x86 processors have a 64 byte cache line.
- * The 64-bit PowerPC processors have a 128 byte cache line.
- * We'll use the larger value to be generally safe.
+/**
+ * A guess for the cacheline size used for padding.
+ *
+ * Most x86 processors have a 64 byte cache line. The 64-bit PowerPC
+ * processors have a 128 byte cache line. We use the larger value to be
+ * generally safe.
+ *
+ * \since This macro is available since SDL 3.0.0.
  */
 #define SDL_CACHELINE_SIZE  128
 
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 7d124a6a84912..5e519c6859d56 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -66,10 +66,18 @@ extern "C" {
  */
 #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
 
-typedef struct SDL_BlitMap SDL_BlitMap;  /* this is an opaque type. */
+/**
+ * An opaque type used in SDL_Surface.
+ *
+ * This is used by SDL to keep track of how blit operations should work
+ * internally; it is not for use directly by applications.
+ *
+ * \since This struct is available since SDL 3.0.0.
+ */
+typedef struct SDL_BlitMap SDL_BlitMap;
 
 /**
- * The scaling mode
+ * The scaling mode.
  *
  * \since This enum is available since SDL 3.0.0.
  */
@@ -81,7 +89,7 @@ typedef enum SDL_ScaleMode
 } SDL_ScaleMode;
 
 /**
- * The flip mode
+ * The flip mode.
  *
  * \since This enum is available since SDL 3.0.0.
  */
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 0d79c7143d791..2070d50cd6533 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -568,49 +568,125 @@ extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
 
-/* Functions used by iOS app delegates to notify SDL about state changes.
- *
- * These functions allow iOS apps that have their own event handling to hook
- * into SDL to generate SDL events. These map directly to iOS-specific
- * events, but since they don't do anything iOS-specific internally, they
- * are available on all platforms, in case they might be useful for some
- * specific paradigm. Most apps do not need to use these directly; SDL's
- * internal event code will handle all this for windows created by
- * SDL_CreateWindow!
- */
+/* Functions used by iOS app delegates to notify SDL about state changes. */
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationWillTerminate.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationDidReceiveMemoryWarning.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationWillResignActive.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void);
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationDidEnterBackground.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationWillEnterForeground.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
 
-/*
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationDidBecomeActive.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
 
 #ifdef SDL_PLATFORM_IOS
-/*
+
+/**
+ * Let iOS apps with external event handling report
+ * onApplicationDidChangeStatusBarOrientation.
+ *
+ * This functions allows iOS apps that have their own event handling to hook
+ * into SDL to generate SDL events. This maps directly to an iOS-specific
+ * event, but since it doesn't do anything iOS-specific internally, it is
+ * available on all platforms, in case it might be useful for some specific
+ * paradigm. Most apps do not need to use this directly; SDL's internal event
+ * code will handle all this for windows created by SDL_CreateWindow!
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 4f1c50825db4c..43e6c339c1331 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -45,19 +45,20 @@ extern "C" {
 typedef Uint32 SDL_DisplayID;
 typedef Uint32 SDL_WindowID;
 
-/*
- *  Global video properties.
- *
- *  - `SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to
- *    the global `wl_display` object used by the Wayland video backend. Can be
- *    set before the video subsystem is initialized to import an external
- *    `wl_display` object from an application or toolkit for use in SDL, or
- *    read after initialization to export the `wl_display` used by the
- *    Wayland video backend. Setting this property after the video subsystem
- *    has been initialized has no effect, and reading it when the video
- *    subsystem is uninitialized will either return the user provided value,
- *    if one was set prior to initialization, or NULL. See
- *    docs/README-wayland.md for more information.
+/* Global video properties... */
+
+/**
+ * The pointer to the global `wl_display` object used by the Wayland video
+ * backend.
+ *
+ * Can be set before the video subsystem is initialized to import an external
+ * `wl_display` object from an application or toolkit for use in SDL, or read
+ * after initialization to export the `wl_display` used by the Wayland video
+ * backend. Setting this property after the video subsystem has been
+ * initialized has no effect, and reading it when the video subsystem is
+ * uninitialized will either return the user provided value, if one was set
+ * prior to initialization, or NULL. See docs/README-wayland.md for more
+ * information.
  */
 #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display"