fnsince: update \since policy for documentation.

Everything in SDL3 up to the ABI lock is reported as available since 3.1.3.
Everything else will be reported as since 3.2.0 (what will be the first
official release).

Also ran a Perl script over the headers to change everything to 3.1.3 that
wasn't an API function, since fnsince.pl can't manage those. If there's a
macro or datatype that has snuck in that needs to be 3.2.0 instead, we'll
have to manually fix it up, but it shouldn't be a big deal in any case.

Reference PR #11304.

include/SDL3/SDL_events.h

@@ -55,7 +55,7 @@ extern "C" {
 /**
  * The types of events that can be delivered.
  *
- * \since This enum is available since SDL 3.0.0.
+ * \since This enum is available since SDL 3.1.3.
  */
 typedef enum SDL_EventType
 {
@@ -257,7 +257,7 @@ typedef enum SDL_EventType
 /**
  * Fields shared by every event
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_CommonEvent
 {
@@ -269,7 +269,7 @@ typedef struct SDL_CommonEvent
 /**
  * Display state change event data (event.display.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_DisplayEvent
 {
@@ -284,7 +284,7 @@ typedef struct SDL_DisplayEvent
 /**
  * Window state change event data (event.window.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_WindowEvent
 {
@@ -299,7 +299,7 @@ typedef struct SDL_WindowEvent
 /**
  * Keyboard device event structure (event.kdevice.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_KeyboardDeviceEvent
 {
@@ -318,7 +318,7 @@ typedef struct SDL_KeyboardDeviceEvent
  * event scancode and modifiers directly from the keyboard layout, bypassing
  * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode().
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  *
  * \sa SDL_GetKeyFromScancode
  * \sa SDL_HINT_KEYCODE_OPTIONS
@@ -345,7 +345,7 @@ typedef struct SDL_KeyboardEvent
  * will be inserted into the editing text. The length is the number of UTF-8
  * characters that will be replaced by new typing.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_TextEditingEvent
 {
@@ -361,7 +361,7 @@ typedef struct SDL_TextEditingEvent
 /**
  * Keyboard IME candidates event structure (event.edit_candidates.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_TextEditingCandidatesEvent
 {
@@ -384,7 +384,7 @@ typedef struct SDL_TextEditingCandidatesEvent
  * This event will never be delivered unless text input is enabled by calling
  * SDL_StartTextInput(). Text input is disabled by default!
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  *
  * \sa SDL_StartTextInput
  * \sa SDL_StopTextInput
@@ -401,7 +401,7 @@ typedef struct SDL_TextInputEvent
 /**
  * Mouse device event structure (event.mdevice.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_MouseDeviceEvent
 {
@@ -414,7 +414,7 @@ typedef struct SDL_MouseDeviceEvent
 /**
  * Mouse motion event structure (event.motion.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_MouseMotionEvent
 {
@@ -433,7 +433,7 @@ typedef struct SDL_MouseMotionEvent
 /**
  * Mouse button event structure (event.button.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_MouseButtonEvent
 {
@@ -453,7 +453,7 @@ typedef struct SDL_MouseButtonEvent
 /**
  * Mouse wheel event structure (event.wheel.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_MouseWheelEvent
 {
@@ -472,7 +472,7 @@ typedef struct SDL_MouseWheelEvent
 /**
  * Joystick axis motion event structure (event.jaxis.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_JoyAxisEvent
 {
@@ -491,7 +491,7 @@ typedef struct SDL_JoyAxisEvent
 /**
  * Joystick trackball motion event structure (event.jball.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_JoyBallEvent
 {
@@ -510,7 +510,7 @@ typedef struct SDL_JoyBallEvent
 /**
  * Joystick hat position change event structure (event.jhat.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_JoyHatEvent
 {
@@ -533,7 +533,7 @@ typedef struct SDL_JoyHatEvent
 /**
  * Joystick button event structure (event.jbutton.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_JoyButtonEvent
 {
@@ -553,7 +553,7 @@ typedef struct SDL_JoyButtonEvent
  * SDL will send JOYSTICK_ADDED events for devices that are already plugged in
  * during SDL_Init.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  *
  * \sa SDL_GamepadDeviceEvent
  */
@@ -568,7 +568,7 @@ typedef struct SDL_JoyDeviceEvent
 /**
  * Joystick battery level change event structure (event.jbattery.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_JoyBatteryEvent
 {
@@ -583,7 +583,7 @@ typedef struct SDL_JoyBatteryEvent
 /**
  * Gamepad axis motion event structure (event.gaxis.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_GamepadAxisEvent
 {
@@ -603,7 +603,7 @@ typedef struct SDL_GamepadAxisEvent
 /**
  * Gamepad button event structure (event.gbutton.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_GamepadButtonEvent
 {
@@ -628,7 +628,7 @@ typedef struct SDL_GamepadButtonEvent
  * in during SDL_Init() and are recognized as gamepads. It will also send
  * events for joysticks that get gamepad mappings at runtime.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  *
  * \sa SDL_JoyDeviceEvent
  */
@@ -643,7 +643,7 @@ typedef struct SDL_GamepadDeviceEvent
 /**
  * Gamepad touchpad event structure (event.gtouchpad.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_GamepadTouchpadEvent
 {
@@ -661,7 +661,7 @@ typedef struct SDL_GamepadTouchpadEvent
 /**
  * Gamepad sensor event structure (event.gsensor.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_GamepadSensorEvent
 {
@@ -677,7 +677,7 @@ typedef struct SDL_GamepadSensorEvent
 /**
  * Audio device event structure (event.adevice.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_AudioDeviceEvent
 {
@@ -694,7 +694,7 @@ typedef struct SDL_AudioDeviceEvent
 /**
  * Camera device event structure (event.cdevice.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_CameraDeviceEvent
 {
@@ -721,7 +721,7 @@ typedef struct SDL_CameraDeviceEvent
  * report a touch outside of the window, which will also be outside of the
  * range.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_TouchFingerEvent
 {
@@ -751,7 +751,7 @@ typedef struct SDL_TouchFingerEvent
  * is there." The pen touching and lifting off from the tablet while not
  * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_PenProximityEvent
 {
@@ -771,7 +771,7 @@ typedef struct SDL_PenProximityEvent
  * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when
  * dealing with pen motion.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_PenMotionEvent
 {
@@ -791,7 +791,7 @@ typedef struct SDL_PenMotionEvent
  * These events come when a pen touches a surface (a tablet, etc), or lifts
  * off from one.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_PenTouchEvent
 {
@@ -813,7 +813,7 @@ typedef struct SDL_PenTouchEvent
  * This is for buttons on the pen itself that the user might click. The pen
  * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_PenButtonEvent
 {
@@ -835,7 +835,7 @@ typedef struct SDL_PenButtonEvent
  * You might get some of these events even if the pen isn't touching the
  * tablet.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_PenAxisEvent
 {
@@ -855,7 +855,7 @@ typedef struct SDL_PenAxisEvent
  * An event used to drop text or request a file open by the system
  * (event.drop.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_DropEvent
 {
@@ -873,7 +873,7 @@ typedef struct SDL_DropEvent
  * An event triggered when the clipboard contents have changed
  * (event.clipboard.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_ClipboardEvent
 {
@@ -888,7 +888,7 @@ typedef struct SDL_ClipboardEvent
 /**
  * Sensor event structure (event.sensor.*)
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_SensorEvent
 {
@@ -903,7 +903,7 @@ typedef struct SDL_SensorEvent
 /**
  * The "quit requested" event
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_QuitEvent
 {
@@ -921,7 +921,7 @@ typedef struct SDL_QuitEvent
  * the programmer; the only requirement is that '''type''' is a value obtained
  * from SDL_RegisterEvents().
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef struct SDL_UserEvent
 {
@@ -938,7 +938,7 @@ typedef struct SDL_UserEvent
 /**
  * The structure for all events in SDL.
  *
- * \since This struct is available since SDL 3.0.0.
+ * \since This struct is available since SDL 3.1.3.
  */
 typedef union SDL_Event
 {
@@ -1019,7 +1019,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
  * polling or waiting for events (e.g. you are filtering them), then you must
  * call SDL_PumpEvents() to force an event queue update.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PollEvent
  * \sa SDL_WaitEvent
@@ -1031,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void);
 /**
  * The type of action to request from SDL_PeepEvents().
  *
- * \since This enum is available since SDL 3.0.0.
+ * \since This enum is available since SDL 3.1.3.
  */
 typedef enum SDL_EventAction
 {
@@ -1076,7 +1076,7 @@ typedef enum SDL_EventAction
  * \returns the number of events actually stored or -1 on failure; call
  *          SDL_GetError() for more information.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PollEvent
  * \sa SDL_PumpEvents
@@ -1095,7 +1095,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
  * \returns true if events matching `type` are present, or false if events
  *          matching `type` are not present.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_HasEvents
  */
@@ -1114,7 +1114,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type);
  * \returns true if events with type >= `minType` and <= `maxType` are
  *          present, or false if not.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_HasEvents
  */
@@ -1140,7 +1140,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
  *
  * \param type the type of event to be cleared; see SDL_EventType for details.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_FlushEvents
  */
@@ -1165,7 +1165,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
  * \param maxType the high end of event type to be cleared, inclusive; see
  *                SDL_EventType for details.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_FlushEvent
  */
@@ -1207,7 +1207,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
  *              the queue, or NULL.
  * \returns true if this got an event or false if there are none available.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PushEvent
  * \sa SDL_WaitEvent
@@ -1229,7 +1229,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event);
  * \returns true on success or false if there was an error while waiting for
  *          events; call SDL_GetError() for more information.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PollEvent
  * \sa SDL_PushEvent
@@ -1257,7 +1257,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event);
  * \returns true if this got an event or false if the timeout elapsed without
  *          any events available.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PollEvent
  * \sa SDL_PushEvent
@@ -1291,7 +1291,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 t
  *          call SDL_GetError() for more information. A common reason for
  *          error is the event queue being full.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PeepEvents
  * \sa SDL_PollEvent
@@ -1313,7 +1313,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event);
  *               application is responsible for locking resources the callback
  *               touches that need to be protected.
  *
- * \since This datatype is available since SDL 3.0.0.
+ * \since This datatype is available since SDL 3.1.3.
  *
  * \sa SDL_SetEventFilter
  * \sa SDL_AddEventWatch
@@ -1358,7 +1358,7 @@ typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
  *               the application is responsible for locking resources the
  *               callback touches that need to be protected.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_AddEventWatch
  * \sa SDL_SetEventEnabled
@@ -1379,7 +1379,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void
  *                 be stored here.
  * \returns true on success or false if there is no event filter set.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_SetEventFilter
  */
@@ -1410,7 +1410,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, voi
  *
  * \threadsafety It is safe to call this function from any thread.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_RemoveEventWatch
  * \sa SDL_SetEventFilter
@@ -1426,7 +1426,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void
  * \param filter the function originally passed to SDL_AddEventWatch().
  * \param userdata the pointer originally passed to SDL_AddEventWatch().
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_AddEventWatch
  */
@@ -1443,7 +1443,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo
  * \param filter the SDL_EventFilter function to call when an event happens.
  * \param userdata a pointer that is passed to `filter`.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_GetEventFilter
  * \sa SDL_SetEventFilter
@@ -1456,7 +1456,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *
  * \param type the type of event; see SDL_EventType for details.
  * \param enabled whether to process the event or not.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_EventEnabled
  */
@@ -1468,7 +1468,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled);
  * \param type the type of event; see SDL_EventType for details.
  * \returns true if the event is being processed, false otherwise.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_SetEventEnabled
  */
@@ -1482,7 +1482,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type);
  * \returns the beginning event number, or 0 if numevents is invalid or if
  *          there are not enough user-defined events left.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PushEvent
  */
@@ -1494,7 +1494,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
  * \param event an event containing a `windowID`.
  * \returns the associated window on success or NULL if there is none.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.1.3.
  *
  * \sa SDL_PollEvent
  * \sa SDL_WaitEvent