include: Filling in more documentation gaps.

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;
 
 

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.
+ * A guess for the cacheline size used for padding.
- * The 64-bit PowerPC processors have a 128 byte cache line.
+ *
- * We'll use the larger value to be generally safe.
+ * 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
 

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.
  */

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.
+/* 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!
- */
 
-/*
+/**
+ * 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);

include/SDL3/SDL_video.h

@@ -45,19 +45,20 @@ extern "C" {
 typedef Uint32 SDL_DisplayID;
 typedef Uint32 SDL_WindowID;
 
-/*
+/* Global video properties... */
- *  Global video properties.
+
+/**
+ * The pointer to the global `wl_display` object used by the Wayland video
+ * backend.
  *
- *  - `SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to
+ * Can be set before the video subsystem is initialized to import an external
- *    the global `wl_display` object used by the Wayland video backend. Can be
+ * `wl_display` object from an application or toolkit for use in SDL, or read
- *    set before the video subsystem is initialized to import an external
+ * after initialization to export the `wl_display` used by the Wayland video
- *    `wl_display` object from an application or toolkit for use in SDL, or
+ * backend. Setting this property after the video subsystem has been
- *    read after initialization to export the `wl_display` used by the
+ * initialized has no effect, and reading it when the video subsystem is
- *    Wayland video backend. Setting this property after the video subsystem
+ * uninitialized will either return the user provided value, if one was set
- *    has been initialized has no effect, and reading it when the video
+ * prior to initialization, or NULL. See docs/README-wayland.md for more
- *    subsystem is uninitialized will either return the user provided value,
+ * information.
- *    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"