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 165bfd3e83)
(cherry picked from commit 90aaa23977)
(cherry picked from commit 7d27ca282e)
(cherry picked from commit 6fc31b7f0b)
(cherry picked from commit c71c53c406)
(cherry picked from commit c9b7ca0c42)
(cherry picked from commit e2bc4be482)
(cherry picked from commit ae4fb50316)
(cherry picked from commit 6f45f97af0)
(cherry picked from commit d2ca570050)
(cherry picked from commit 73500019ea)
(cherry picked from commit 72ed7d0f87)
(cherry picked from commit 2aacf018f0)

[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