From 49e47b523a327a8d26951738bf22953d60598ff2 Mon Sep 17 00:00:00 2001
From: Sylvain <[EMAIL REDACTED]>
Date: Sun, 12 Feb 2023 10:09:42 +0100
Subject: [PATCH] Update `\returns` to the generic form
---
include/SDL3/SDL_audio.h | 15 ++++++-----
include/SDL3/SDL_gamepad.h | 15 +++++++----
include/SDL3/SDL_hidapi.h | 21 ++++++++++-----
include/SDL3/SDL_joystick.h | 21 ++++++++++-----
include/SDL3/SDL_main.h | 3 ++-
include/SDL3/SDL_misc.h | 4 +--
include/SDL3/SDL_mouse.h | 6 ++---
include/SDL3/SDL_mutex.h | 6 +++--
include/SDL3/SDL_pixels.h | 4 +--
include/SDL3/SDL_render.h | 53 +++++++++++++++++++++++--------------
include/SDL3/SDL_sensor.h | 3 ++-
include/SDL3/SDL_system.h | 9 ++++---
include/SDL3/SDL_video.h | 10 +++----
include/SDL3/SDL_vulkan.h | 2 +-
14 files changed, 106 insertions(+), 66 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 7db605da26ea..3f626255975d 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -356,7 +356,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
* \param iscapture non-zero to query the list of recording devices, zero to
* query the list of output devices.
* \param spec The SDL_AudioSpec to be initialized by this function.
- * \returns 0 on success, nonzero on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -390,7 +391,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* \param spec The SDL_AudioSpec to be initialized by this function.
* \param iscapture non-zero to query the default recording device, zero to
* query the default output device.
- * \returns 0 on success, nonzero on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -729,7 +731,8 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(SDL_AudioFormat s
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
- * \returns 0 on success, or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1146,10 +1149,10 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
* \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output
* \param dst_data Will be filled with a pointer to converted audio data,
- * which should be freed with SDL_free().
+ * which should be freed with SDL_free(). On error, it will be NULL.
* \param dst_len Will be filled with the len of dst_data
- * \returns 0 on success or a negative error code on failure. On error,
- * *dst_data will be NULL and so not allocated.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index a3054f5dc2b0..814e4c4d1ed7 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -897,7 +897,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_
* \param gamepad The gamepad to update
* \param type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled
- * \returns 0 or -1 if an error occurred.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -935,7 +936,8 @@ extern DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad,
* \param type The type of sensor to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
- * \returns 0 or -1 if an error occurred.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -977,7 +979,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if trigger rumble isn't supported on this gamepad
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1029,7 +1032,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasRumbleTriggers(SDL_Gamepad *gamep
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
- * \returns 0, or -1 if this gamepad does not have a modifiable LED
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1041,7 +1045,8 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, U
* \param gamepad The gamepad to affect
* \param data The data to send to the gamepad
* \param size The size of the data to send to the gamepad
- * \returns 0, or -1 if this gamepad or driver doesn't support effect packets
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h
index 2043991013a6..53049700dc7d 100644
--- a/include/SDL3/SDL_hidapi.h
+++ b/include/SDL3/SDL_hidapi.h
@@ -133,7 +133,8 @@ typedef struct SDL_hid_device_info
*
* Each call to this function should have a matching call to SDL_hid_exit()
*
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -147,7 +148,8 @@ extern DECLSPEC int SDLCALL SDL_hid_init(void);
* This function frees all of the static data associated with HIDAPI. It
* should be called at the end of execution to avoid memory leaks.
*
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -322,7 +324,8 @@ extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *dat
* \param dev A device handle returned from SDL_hid_open().
* \param nonblock enable or not the nonblocking reads - 1 to enable
* nonblocking - 0 to disable nonblocking.
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -391,7 +394,8 @@ extern DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev);
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -403,7 +407,8 @@ extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev,
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -415,7 +420,8 @@ extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wcha
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -428,7 +434,8 @@ extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev
* \param string_index The index of the string to get.
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
- * \returns 0 on success and -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 840f3b5cf251..71b5aeb9d449 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -378,7 +378,8 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
*
* \param instance_id the joystick instance ID, previously returned from
* SDL_AttachVirtualJoystick()
- * \returns 0 on success, or -1 if an error occurred.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -410,7 +411,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_i
* \param joystick the virtual joystick on which to set state.
* \param axis the specific axis on the virtual joystick to set.
* \param value the new value for the specified axis.
- * \returns 0 on success, -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -428,7 +430,8 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, i
* \param joystick the virtual joystick on which to set state.
* \param button the specific button on the virtual joystick to set.
* \param value the new value for the specified button.
- * \returns 0 on success, -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -446,7 +449,8 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick,
* \param joystick the virtual joystick on which to set state.
* \param hat the specific hat on the virtual joystick to set.
* \param value the new value for the specified hat.
- * \returns 0 on success, -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -898,7 +902,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 lo
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if trigger rumble isn't supported on this joystick
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -953,7 +958,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
- * \returns 0 on success, -1 if this joystick does not have a modifiable LED
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -965,7 +971,8 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red
* \param joystick The joystick to affect
* \param data The data to send to the joystick
* \param size The size of the data to send to the joystick
- * \returns 0, or -1 if this joystick or driver doesn't support effect packets
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index d011e1cf5d4a..573988379931 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -219,7 +219,8 @@ extern DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func mai
* what is specified here.
* \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL
* will use `GetModuleHandle(NULL)` instead.
- * \returns 0 on success, -1 on error. SDL_GetError() may have details.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_misc.h b/include/SDL3/SDL_misc.h
index 7c02ca54bac8..42426b5291d8 100644
--- a/include/SDL3/SDL_misc.h
+++ b/include/SDL3/SDL_misc.h
@@ -61,8 +61,8 @@ extern "C" {
*
* \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
* local files, if supported.
- * \returns 0 on success, or -1 on error; call SDL_GetError() for more
- * information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h
index c90d53d7c88c..04df4e3f705f 100644
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@@ -214,8 +214,6 @@ extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(float x, float y);
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
- * If relative mode is not supported, this returns -1.
- *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetRelativeMouseMode
@@ -259,8 +257,8 @@ extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
* `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.
*
* \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
- * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
- * information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index f406e2210f4e..e4c9956447c8 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -166,7 +166,8 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
* other threads in the system (this is known as a "recursive mutex").
*
* \param mutex the mutex to lock
- * \returns 0, or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -208,7 +209,8 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex) SDL_TRY_ACQUIRE(
* It is also an error to unlock a mutex that isn't locked at all.
*
* \param mutex the mutex to unlock.
- * \returns 0, or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h
index 705add6fbfde..ca980beab88a 100644
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@@ -462,8 +462,8 @@ extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
* \param colors an array of SDL_Color structures to copy into the palette
* \param firstcolor the index of the first palette entry to modify
* \param ncolors the number of entries to modify
- * \returns 0 on success or a negative error code if not all of the colors
- * could be set; call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 46702596107e..5a2df35c00c5 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -214,8 +214,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index);
* SDL_CreateWindow())
* \param window a pointer filled with the window, or NULL on error
* \param renderer a pointer filled with the renderer, or NULL on error
- * \returns 0 on success, or -1 on error; call SDL_GetError() for more
- * information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -567,7 +567,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_Bl
*
* \param texture The texture to update.
* \param scaleMode the SDL_ScaleMode to use for texture scaling.
- * \returns 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -580,7 +581,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_Sc
*
* \param texture the texture to query.
* \param scaleMode a pointer filled in with the current scale mode.
- * \returns 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -593,7 +595,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_Sc
*
* \param texture the texture to update.
* \param userdata the pointer to associate with the texture.
- * \returns 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -665,7 +668,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Re
* \param Vplane the raw pixel data for the V plane
* \param Vpitch the number of bytes between rows of pixel data for the V
* plane
- * \returns 0 on success or -1 if the texture is not valid; call
+ * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@@ -694,7 +697,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture,
* \param UVplane the raw pixel data for the UV plane.
* \param UVpitch the number of bytes between rows of pixel data for the UV
* plane.
- * \returns 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -752,14 +756,14 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture,
* The returned surface is freed internally after calling SDL_UnlockTexture()
* or SDL_DestroyTexture(). The caller should not free it.
*
- * \param texture the texture to lock for access, which was created with
+ * \param texture the texture to lock for access, which must be created with
* `SDL_TEXTUREACCESS_STREAMING`
* \param rect a pointer to the rectangle to lock for access. If the rect is
* NULL, the entire texture will be locked
* \param surface this is filled in with an SDL surface representing the
* locked area
- * \returns 0 on success, or -1 if the texture is not valid or was not created
- * with `SDL_TEXTUREACCESS_STREAMING`
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1173,7 +1177,8 @@ extern DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, flo
* \param renderer The renderer which should draw multiple points.
* \param points The points to draw
* \param count The number of points to draw
- * \returns 0 on success, or -1 on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1200,7 +1205,8 @@ extern DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, flo
* \param renderer The renderer which should draw multiple lines.
* \param points The points along the lines
* \param count The number of points, drawing count-1 lines
- * \returns 0 on success, or -1 on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1225,7 +1231,8 @@ extern DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRe
* \param renderer The renderer which should draw multiple rectangles.
* \param rects A pointer to an array of destination rectangles.
* \param count The number of rectangles.
- * \returns 0 on success, or -1 on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1251,7 +1258,8 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL
* \param renderer The renderer which should fill multiple rectangles.
* \param rects A pointer to an array of destination rectangles.
* \param count The number of rectangles.
- * \returns 0 on success, or -1 on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1290,7 +1298,8 @@ extern DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Textur
* around dstrect.w/2, dstrect.h/2).
* \param flip An SDL_RendererFlip value stating which flipping actions should
* be performed on the texture
- * \returns 0 on success, or -1 on error
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1342,7 +1351,8 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
* if NULL all vertices will be rendered in sequential order.
* \param num_indices Number of indices.
* \param size_indices Index size: 1 (byte), 2 (short), 4 (int)
- * \returns 0 on success, or -1 if the operation is not supported
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1517,7 +1527,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer *renderer);
* texture width or NULL if you don't need that value
* \param texh a pointer to a float value which will be filled with the
* texture height or NULL if you don't need that value
- * \returns 0 on success, or -1 if the operation is not supported; call
+ * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@@ -1533,7 +1543,8 @@ extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw
* See SDL_GL_BindTexture() for examples on how to use these functions
*
* \param texture the texture to unbind from the current OpenGL/ES/ES2 context
- * \returns 0 on success, or -1 if the operation is not supported
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1584,7 +1595,8 @@ extern DECLSPEC void *SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer *ren
*
* \param renderer The renderer to toggle
* \param vsync 1 for on, 0 for off. All other values are reserved
- * \returns a 0 int on success, or non-zero on failure
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -1596,7 +1608,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync
* \param renderer The renderer to toggle
* \param vsync an int filled with 1 for on, 0 for off. All other values are
* reserved
- * \returns a 0 int on success, or non-zero on failure
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index a9b3c8387ad4..ad0d980d3ca6 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -241,7 +241,8 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorInstanceID(SDL_Sensor *sensor)
* \param sensor The SDL_Sensor object to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
- * \returns 0 or -1 if an error occurred.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index b1b7c652a859..9c969f99e130 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -173,7 +173,8 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio
* \param sdlPriority The new SDL_ThreadPriority value.
* \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR,
* SCHED_OTHER, etc...)
- * \returns 0 on success, or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -443,7 +444,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis
* \param gravity where the notification should appear on the screen.
* \param xoffset set this parameter only when gravity >=0
* \param yoffset set this parameter only when gravity >=0
- * \returns 0 if success, -1 if any error occurs.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -603,7 +605,8 @@ typedef struct XTaskQueueObject * XTaskQueueHandle;
* leak.
*
* \param outTaskQueue a pointer to be filled in with task queue handle.
- * \returns 0 if success, -1 if any error occurs.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 2e273c8bd9b0..b746dd5ebc21 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -1501,7 +1501,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
* \param window the window to set hit-testing on
* \param callback the function to call when doing a hit-test
* \param callback_data an app-defined void pointer passed to **callback**
- * \returns 0 on success or -1 on error (including unsupported); call
+ * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@@ -1896,8 +1896,8 @@ extern DECLSPEC void SDLCALL SDL_EGL_SetEGLAttributeCallbacks(SDL_EGLAttribArray
*
* \param interval 0 for immediate updates, 1 for updates synchronized with
* the vertical retrace, -1 for adaptive vsync
- * \returns 0 on success or -1 if setting the swap interval is not supported;
- * call SDL_GetError() for more information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -1915,8 +1915,8 @@ extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
* synchronization, 1 if the buffer swap is synchronized with
* the vertical retrace, and -1 if late swaps happen
* immediately instead of waiting for the next retrace
- * \returns 0 on success or -1 error. call SDL_GetError() for more
- * information.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h
index ce06e3a28d0e..24f79b32e013 100644
--- a/include/SDL3/SDL_vulkan.h
+++ b/include/SDL3/SDL_vulkan.h
@@ -95,7 +95,7 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
* library version.
*
* \param path The platform dependent Vulkan loader library name or NULL
- * \returns 0 on success or -1 if the library couldn't be loaded; call
+ * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
(Patch may be truncated, please check the link at the top of this post.)