headers: selected sdl-wiki-bot-authored updates from main branch

to eliminate discrepancies between release-3.4.x and main branches.

(cherry picked from commit 165bfd3e8328307cbffc2ed7cc4f0e101cb82ba5)
(cherry picked from commit 90aaa239772d7d9225a0b86b48d2c48ce95f2ce6)
(cherry picked from commit 7d27ca282eb1ca85bdfd20d4e19227c63a3f122c)
(cherry picked from commit 6fc31b7f0b80bba225281d54cd25fd74bf8ccb73)
(cherry picked from commit c71c53c4069aea8ca7239b1c7405a58aa8eacc9e)
(cherry picked from commit c9b7ca0c42107d514c77ea6114980ff453b5f101)
(cherry picked from commit e2bc4be482cb1978d2ff1a29cff927271cc44a34)
(cherry picked from commit ae4fb503168e1860a46067657103e1a56de5f5c7)
(cherry picked from commit 6f45f97af0ebaa963f2efb971540b08b199e264c)
(cherry picked from commit d2ca570050dc8cc8427c6c7504699695de2810b9)
(cherry picked from commit 73500019ea513f131f322d21dc4d42b35764f118)
(cherry picked from commit 72ed7d0f8715f8dbfb0c8dcd4103cd92c9573c72)
(cherry picked from commit 2aacf018f0aa454177d774240eb34f064d8f36cb)

[ci skip]

include/SDL3/SDL_audio.h

@@ -1349,7 +1349,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt
  *
  * \since This function is available since SDL 3.2.0.
  *
- * \sa SDL_SetAudioStreamInputChannelMap
+ * \sa SDL_SetAudioStreamOutputChannelMap
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
 

include/SDL3/SDL_events.h

@@ -1258,8 +1258,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
  * If `event` is not NULL, the next event is removed from the queue and stored
  * in the SDL_Event structure pointed to by `event`.
  *
- * If `event` is NULL, it simply returns true if there is an event in the queue,
- * but will not remove it from the queue.
+ * If `event` is NULL, it simply returns true if there is an event in the
+ * queue, but will not remove it from the queue.
  *
  * As this function may implicitly call SDL_PumpEvents(), you can only call
  * this function in the thread that initialized the video subsystem.

include/SDL3/SDL_filesystem.h

@@ -241,8 +241,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder);
 /**
  * Types of filesystem entries.
  *
- * Note that there may be other sorts of items on a filesystem: devices,
- * named pipes, etc. They are currently reported as SDL_PATHTYPE_OTHER.
+ * Note that there may be other sorts of items on a filesystem: devices, named
+ * pipes, etc. They are currently reported as SDL_PATHTYPE_OTHER.
  *
  * \since This enum is available since SDL 3.2.0.
  *
@@ -456,9 +456,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *n
 /**
  * Get information about a filesystem path.
  *
- * Symlinks, on filesystems that support them, are always followed, so you will
- * always get information on what the symlink eventually points to, and not the
- * symlink itself.
+ * Symlinks, on filesystems that support them, are always followed, so you
+ * will always get information on what the symlink eventually points to, and
+ * not the symlink itself.
  *
  * \param path the path to query.
  * \param info a pointer filled in with information about the path, or NULL to

include/SDL3/SDL_gpu.h

@@ -1398,12 +1398,12 @@ typedef struct SDL_GPUViewport
  * SDL_DownloadFromGPUTexture are used as default values respectively and data
  * is considered to be tightly packed.
  *
- * **WARNING**: On some older/integrated hardware, Direct3D 12 requires texture
- * data row pitch to be 256 byte aligned, and offsets to be aligned to 512 bytes.
- * If they are not, SDL will make a temporary copy of the data that is properly
- * aligned, but this adds overhead to the transfer process. Apps can avoid this
- * by aligning their data appropriately, or using a different GPU backend than
- * Direct3D 12.
+ * **WARNING**: On some older/integrated hardware, Direct3D 12 requires
+ * texture data row pitch to be 256 byte aligned, and offsets to be aligned to
+ * 512 bytes. If they are not, SDL will make a temporary copy of the data that
+ * is properly aligned, but this adds overhead to the transfer process. Apps
+ * can avoid this by aligning their data appropriately, or using a different
+ * GPU backend than Direct3D 12.
  *
  * \since This struct is available since SDL 3.2.0.
  *

include/SDL3/SDL_haptic.h

@@ -1392,7 +1392,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic);
  * \since This function is available since SDL 3.2.0.
  *
  * \sa SDL_RunHapticEffect
- * \sa SDL_StopHapticEffects
+ * \sa SDL_StopHapticEffect
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic);
 

include/SDL3/SDL_hints.h

@@ -3033,8 +3033,8 @@ extern "C" {
  *
  * - "0": Force a request for an OpenGL context that is _not_ sRGB-capable.
  * - "1": Force a request for an OpenGL context that _is_ sRGB-capable.
- * - "skip": Don't make any request for an sRGB-capable context
- *   (don't specify the attribute at all during context creation time).
+ * - "skip": Don't make any request for an sRGB-capable context (don't specify
+ *   the attribute at all during context creation time).
  * - any other string is undefined behavior.
  *
  * If unset, or set to an empty string, SDL will make a request using the
@@ -4848,7 +4848,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool defau
  * A callback used to send notifications of hint value changes.
  *
  * This is called an initial time during SDL_AddHintCallback with the hint's
- * current value, and then again each time the hint's value changes.
+ * current value, and then again each time the hint's value changes. In the
+ * initial call, the current value is in both `oldValue` and `newValue`.
  *
  * \param userdata what was passed as `userdata` to SDL_AddHintCallback().
  * \param name what was passed as `name` to SDL_AddHintCallback().

include/SDL3/SDL_log.h

@@ -487,7 +487,8 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_
 /**
  * Get the default log output function.
  *
- * \returns the default log output callback.
+ * \returns the default log output callback. It should be called with NULL for
+ *          the userdata argument.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_main.h

@@ -333,7 +333,8 @@ extern "C" {
  * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
  *          terminate with success, SDL_APP_CONTINUE to continue.
  *
- * \threadsafety This function is called once by SDL, at startup, on a single thread.
+ * \threadsafety This function is called once by SDL, at startup, on a single
+ *               thread.
  *
  * \since This function is available since SDL 3.2.0.
  *

include/SDL3/SDL_mutex.h

@@ -380,7 +380,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQU
  *
  * \param mutex the mutex to unlock.
  *
- * \threadsafety This call must be paired with a previous locking call on the same thread.
+ * \threadsafety This call must be paired with a previous locking call on the
+ *               same thread.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -627,7 +628,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock)
  *
  * \param rwlock the rwlock to unlock.
  *
- * \threadsafety This call must be paired with a previous locking call on the same thread.
+ * \threadsafety This call must be paired with a previous locking call on the
+ *               same thread.
  *
  * \since This function is available since SDL 3.2.0.
  *

include/SDL3/SDL_pen.h

@@ -54,11 +54,11 @@
  * example, some platforms can manage multiple devices at the same time, but
  * others will make any connected pens look like a single logical device, much
  * how all USB mice connected to a computer will move the same system cursor.
- * cursor. Other platforms might not support pen buttons, or the distance
- * axis, etc. Very few platforms can even report _what_ functionality the pen
- * supports in the first place, so best practices is to either build UI to let
- * the user configure their pens, or be prepared to handle new functionality
- * for a pen the first time an event is reported.
+ * Other platforms might not support pen buttons, or the distance axis, etc.
+ * Very few platforms can even report _what_ functionality the pen supports in
+ * the first place, so best practices is to either build UI to let the user
+ * configure their pens, or be prepared to handle new functionality for a pen
+ * the first time an event is reported.
  */
 
 #ifndef SDL_pen_h_

include/SDL3/SDL_rect.h

@@ -435,7 +435,7 @@ SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b
  *
  * \since This function is available since SDL 3.2.0.
  *
- * \sa SDL_GetRectIntersection
+ * \sa SDL_GetRectIntersectionFloat
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B);
 

include/SDL3/SDL_render.h

@@ -754,8 +754,6 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende
  *
  * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
  *   associated with the texture, if you want to wrap an existing texture.
- * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
- *   associated with the texture, if you want to wrap an existing texture.
  * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
  *   associated with the UV plane of an NV12 texture, if you want to wrap an
  *   existing texture.

include/SDL3/SDL_storage.h

@@ -568,7 +568,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *stor
  * Remove a file or an empty directory in a writable storage container.
  *
  * \param storage a storage container.
- * \param path the path of the directory to enumerate.
+ * \param path the path to remove from the filesystem.
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
  *

include/SDL3/SDL_thread.h

@@ -461,8 +461,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority
  *               function by its 'return', or -1 if the thread has been
  *               detached or isn't valid, may be NULL.
  *
- * \threadsafety It is safe to call this function from any thread, but only
- *               a single thread can wait any specific thread to finish.
+ * \threadsafety It is safe to call this function from any thread, but only a
+ *               single thread can wait any specific thread to finish.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -512,11 +512,11 @@ extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *threa
  *
  * It is safe to pass NULL to this function; it is a no-op.
  *
- * \threadsafety It is safe to call this function from any thread.
- *
  * \param thread the SDL_Thread pointer that was returned from the
  *               SDL_CreateThread() call that started this thread.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.2.0.
  *
  * \sa SDL_CreateThread