SDL: SDL_JoystickEventState: Make documentation and implementation match. (eb053)

From eb053c7f3fd3c7515d57bc3ecd5abee5f37e781e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 8 May 2024 16:35:10 -0400
Subject: [PATCH] SDL_JoystickEventState: Make documentation and implementation
 match.

This changes the `SDL_EVENTS_DISABLED` path's return value from SDL_DISABLE
to SDL_IGNORE to match expectations, but doesn't actually change the ABI,
since these two symbols are both zero.

Fixes https://github.com/libsdl-org/sdlwiki/issues/460

(cherry picked from commit 7d60ff996542ff023caec9bdb23649731683c5ef)
---
 include/SDL_joystick.h      | 15 ++++++++++-----
 src/joystick/SDL_joystick.c |  2 +-
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index 561e01099cede..7a3faf841c891 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -790,12 +790,17 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
  * **WARNING**: Calling this function may delete all events currently in SDL's
  * event queue.
  *
- * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
- * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
- *          call SDL_GetError() for more information.
+ * While `param` is meant to be one of `SDL_QUERY`, `SDL_IGNORE`, or
+ * `SDL_ENABLE`, this function accepts any value, with any non-zero value that
+ * isn't `SDL_QUERY` being treated as `SDL_ENABLE`.
  *
- *          If `state` is `SDL_QUERY` then the current state is returned,
- *          otherwise the new processing state is returned.
+ * If SDL was built with events disabled (extremely uncommon!), this will
+ * do nothing and always return `SDL_IGNORE`.
+ *
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns If `state` is `SDL_QUERY` then the current state is returned,
+ *          otherwise `state` is returned (even if it was not one of the
+ *          allowed values).
  *
  * \since This function is available since SDL 2.0.0.
  *
diff --git a/src/joystick/SDL_joystick.c b/src/joystick/SDL_joystick.c
index 05c9807c26eaf..73c63c5d777b3 100644
--- a/src/joystick/SDL_joystick.c
+++ b/src/joystick/SDL_joystick.c
@@ -2220,7 +2220,7 @@ void SDL_JoystickUpdate(void)
 int SDL_JoystickEventState(int state)
 {
 #ifdef SDL_EVENTS_DISABLED
-    return SDL_DISABLE;
+    return SDL_IGNORE;
 #else
     const Uint32 event_list[] = {
         SDL_JOYAXISMOTION, SDL_JOYBALLMOTION, SDL_JOYHATMOTION,