Made return value descriptions more consistent across the API

include/SDL3/SDL_audio.h

@@ -480,8 +480,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *
  * \param count a pointer filled in with the number of devices returned. NULL
  *              is allowed.
  * \returns a 0 terminated array of device instance IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -498,7 +498,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioRecordingDevices(int
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param devid the instance ID of the device to query.
- * \returns the name of the audio device, or NULL on error.
+ * \returns the name of the audio device, or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -633,7 +634,7 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDe
  *              default device.
  * \param spec the requested device configuration. Can be NULL to use
  *             reasonable defaults.
- * \returns the device ID on success, 0 on error; call SDL_GetError() for more
+ * \returns the device ID on success or 0 on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -738,7 +739,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
  * this function will always return -1.0f when used on physical devices.
  *
  * \param devid the audio device to query.
- * \returns the gain of the device, or -1.0f on error.
+ * \returns the gain of the device or -1.0f on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -771,7 +773,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid
  *
  * \param devid the audio device on which to change gain.
  * \param gain the gain. 1.0f is no change, 0.0f is silence.
- * \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.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -827,8 +830,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
  * \param devid an audio device to bind a stream to.
  * \param streams an array of audio streams to unbind.
  * \param num_streams number streams listed in the `streams` array.
- * \returns 0 on success, -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.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -848,7 +851,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD
  *
  * \param devid an audio device to bind a stream to.
  * \param stream an audio stream to bind to a device.
- * \returns 0 on success, -1 on error; call SDL_GetError() for more
+ * \returns 0 on success or a negative error code on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -922,7 +925,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
  *
  * \param src_spec the format details of the input audio.
  * \param dst_spec the format details of the output audio.
- * \returns a new audio stream on success, or NULL on failure.
+ * \returns a new audio stream on success or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -955,7 +959,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
  * \param stream the SDL_AudioStream to query.
  * \param src_spec where to store the input audio format; ignored if NULL.
  * \param dst_spec where to store the output audio format; ignored if NULL.
- * \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.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -986,7 +991,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
  *                 changed.
  * \param dst_spec the new format of the audio output; if NULL, it is not
  *                 changed.
- * \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.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -1004,7 +1010,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream
  * Get the frequency ratio of an audio stream.
  *
  * \param stream the SDL_AudioStream to query.
- * \returns the frequency ratio of the stream, or 0.0 on error.
+ * \returns the frequency ratio of the stream or 0.0 on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -1030,7 +1037,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
  * \param stream the stream the frequency ratio is being changed.
  * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
  *              and 100.
- * \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.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -1051,7 +1059,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
  * Audio streams default to a gain of 1.0f (no change in output).
  *
  * \param stream the SDL_AudioStream to query.
- * \returns the gain of the stream, or -1.0f on error.
+ * \returns the gain of the stream or -1.0f on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -1075,7 +1084,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream
  *
  * \param stream the stream on which the gain is being changed.
  * \param gain the gain. 1.0f is no change, 0.0f is silence.
- * \returns 0 on success, or -1 on error.
+ * \returns 0 on successor a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -1173,7 +1183,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_A
  * \param stream the SDL_AudioStream to change.
  * \param chmap the new channel map, NULL to reset to default.
  * \param count The number of channels in the map.
- * \returns 0 on success, -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running. Don't change the
@@ -1219,7 +1230,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStrea
  * \param stream the SDL_AudioStream to change.
  * \param chmap the new channel map, NULL to reset to default.
  * \param count The number of channels in the map.
- * \returns 0 on success, -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running. Don't change the
@@ -1277,7 +1289,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
  * \param stream the stream the audio is being requested from.
  * \param buf a buffer to fill with audio data.
  * \param len the maximum number of bytes to fill.
- * \returns the number of bytes read from the stream, or -1 on error.
+ * \returns the number of bytes read from the stream or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread, but if the
  *               stream has a callback set, the caller might need to manage
@@ -1558,7 +1571,8 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
  *                 stream.
  * \param userdata an opaque pointer provided to the callback for its own
  *                 personal use.
- * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information. This only fails if `stream` is NULL.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1606,7 +1620,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s
  *                 stream.
  * \param userdata an opaque pointer provided to the callback for its own
  *                 personal use.
- * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
+ * \returns 0 on success or a negative error code on failure; call
+ *            SDL_GetError() for more information. This only fails if `stream` is NULL.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1687,7 +1702,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
  *                 necessary.
  * \param userdata app-controlled pointer passed to callback. Can be NULL.
  *                 Ignored if callback is NULL.
- * \returns an audio stream on success, ready to use. NULL on error; call
+ * \returns an audio stream on success, ready to use, or NULL on failure; call
  *          SDL_GetError() for more information. When done with this stream,
  *          call SDL_DestroyAudioStream to free resources and close the
  *          device.
@@ -1783,8 +1798,8 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
  * \param devid the ID of an opened audio device.
  * \param callback a callback function to be called. Can be NULL.
  * \param userdata app-controlled pointer passed to callback. Can be NULL.
- * \returns zero on success, -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.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_camera.h

@@ -173,8 +173,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetCurrentCameraDriver(void);
  * \param count a pointer filled in with the number of camera devices. Can be
  *              NULL.
  * \returns a 0 terminated array of camera instance IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free() or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -215,8 +215,8 @@ extern SDL_DECLSPEC SDL_CameraID *SDLCALL SDL_GetCameras(int *count);
  * \param count a pointer filled in with the number of elements in the list.
  *              Can be NULL.
  * \returns a 0 terminated array of SDL_CameraSpecs, which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -233,7 +233,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraSupportedFormats(SDL_Ca
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param instance_id the camera device instance ID.
- * \returns a human-readable device name, or NULL on error; call
+ * \returns a human-readable device name or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -297,7 +297,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI
  * \param instance_id the camera device instance ID.
  * \param spec the desired format for data the device will provide. Can be
  *             NULL.
- * \returns device, or NULL on failure; call SDL_GetError() for more
+ * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_error.h

@@ -56,7 +56,7 @@ extern "C" {
  * \param fmt a printf()-style message format string.
  * \param ... additional parameters matching % tokens in the `fmt` string, if
  *            any.
- * \returns always -1.
+ * \returns -1.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_events.h

@@ -1323,7 +1323,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
  *
  * \param filter an SDL_EventFilter function to call when an event happens.
  * \param userdata a pointer that is passed to `filter`.
- * \returns 0 on success, or a negative error code on failure; call
+ * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_gamepad.h

@@ -301,7 +301,7 @@ typedef struct SDL_GamepadBinding
  *
  * \param mapping the mapping string.
  * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
- *          -1 on error; call SDL_GetError() for more information.
+ *          -1 on failure; call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -332,7 +332,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
  * \param src the data stream for the mappings to be added.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
- * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ * \returns the number of mappings added or -1 on failure; call SDL_GetError()
  *          for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
  * Windows, etc).
  *
  * \param file the mappings file to load.
- * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ * \returns the number of mappings added or -1 on failure; call SDL_GetError()
  *          for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -393,8 +393,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
  *
  * \param count a pointer filled in with the number of mappings returned, can
  *              be NULL.
- * \returns an array of the mapping strings, NULL-terminated. Returns NULL on
- *          error; call SDL_GetError() for more information.
+ * \returns an array of the mapping strings, NULL-terminated, or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -406,7 +406,7 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param guid a structure containing the GUID for which a mapping is desired.
- * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ * \returns a mapping string or NULL on failure; call SDL_GetError() for more
  *          information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -470,7 +470,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
  *
  * \param count a pointer filled in with the number of gamepads returned.
  * \returns a 0 terminated array of joystick instance IDs which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
  *          more details.
  *
  * \since This function is available since SDL 3.0.0.
@@ -971,7 +971,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
  * SDL to crash.
  *
  * \param gamepad the gamepad object that you want to get a joystick from.
- * \returns an SDL_Joystick object; call SDL_GetError() for more information.
+ * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1013,7 +1013,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
  * \param gamepad a gamepad.
  * \param count a pointer filled in with the number of bindings returned.
  * \returns a NULL terminated array of pointers to bindings which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
  *          more details.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1199,7 +1199,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad,
  *
  * \param gamepad a gamepad.
  * \param button a button index (one of the SDL_GamepadButton values).
- * \returns 1 for pressed state or 0 for not pressed state or error; call
+ * \returns 1 for pressed state or 0 for not pressed state or failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_haptic.h

@@ -935,8 +935,8 @@ typedef Uint32 SDL_HapticID;
  * \param count a pointer filled in with the number of haptic devices
  *              returned.
  * \returns a 0 terminated array of haptic device instance IDs which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_hidapi.h

@@ -263,7 +263,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
  * \param serial_number the Serial Number of the device to open (Optionally
  *                      NULL).
  * \returns a pointer to a SDL_hid_device object on success or NULL on
- *          failure.
+ *          failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -277,7 +278,8 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
  *
  * \param path the path name of the device to open.
  * \returns a pointer to a SDL_hid_device object on success or NULL on
- *          failure.
+ *          failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -303,7 +305,8 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path)
  * \param data the data to send, including the report number as the first
  *             byte.
  * \param length the length in bytes of the data to send.
- * \returns the actual number of bytes written and -1 on error.
+ * \returns the actual number of bytes written and -1 on on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -322,7 +325,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
  *               reports, make sure to read an extra byte for the report
  *               number.
  * \param milliseconds timeout in milliseconds or -1 for blocking wait.
- * \returns the actual number of bytes read and -1 on error. If no packet was
+ * \returns the actual number of bytes read and -1 on on failure; call
+ *          SDL_GetError() for more information. If no packet was
  *          available to be read within the timeout period, this function
  *          returns 0.
  *
@@ -342,7 +346,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
  * \param length the number of bytes to read. For devices with multiple
  *               reports, make sure to read an extra byte for the report
  *               number.
- * \returns the actual number of bytes read and -1 on error. If no packet was
+ * \returns the actual number of bytes read and -1 on failure; call
+ *            SDL_GetError() for more information. If no packet was
  *          available to be read and the handle is in non-blocking mode, this
  *          function returns 0.
  *
@@ -387,7 +392,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
  *             byte.
  * \param length the length in bytes of the data to send, including the report
  *               number.
- * \returns the actual number of bytes written and -1 on error.
+ * \returns the actual number of bytes written and -1 on failure; call
+ *            SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -409,7 +415,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
  * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
- *          still in the first byte), or -1 on error.
+ *          still in the first byte), or -1 on on failure; call
+ *                    SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -431,7 +438,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
  * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
- *          still in the first byte), or -1 on error.
+ *          still in the first byte), or -1 on on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -505,8 +513,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
  * Get the device info from a HID device.
  *
  * \param dev a device handle returned from SDL_hid_open().
- * \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL
- *          in the case of failure; call SDL_GetError() for more information.
+ * \returns a pointer to the SDL_hid_device_info for this hid_device or NULL
+ *          on failure; call SDL_GetError() for more information.
  *          This struct is valid until the device is closed with
  *          SDL_hid_close().
  *
@@ -523,7 +531,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi
  * \param dev a device handle returned from SDL_hid_open().
  * \param buf the buffer to copy descriptor into.
  * \param buf_size the size of the buffer in bytes.
- * \returns the number of bytes actually copied, or -1 on error; call
+ * \returns the number of bytes actually copied or -1 on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_iostream.h

@@ -224,7 +224,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  * \param file a UTF-8 string representing the filename to open.
  * \param mode an ASCII string representing the mode to be used for opening
  *             the file.
- * \returns a pointer to the SDL_IOStream structure that is created, or NULL
+ * \returns a pointer to the SDL_IOStream structure that is created or NULL
  *          on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -258,7 +258,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromFile(const char *file, const
  *
  * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
  * \param size the buffer size, in bytes.
- * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -291,7 +291,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromMem(void *mem, size_t size);
  *
  * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
  * \param size the buffer size, in bytes.
- * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -319,7 +319,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromConstMem(const void *mem, si
  * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
  *   multiples of this size, defaulting to 1024.
  *
- * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
+ * \returns a pointer to a new SDL_IOStream structure or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -354,7 +354,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
  * \param iface the function pointers that implement this SDL_IOStream.
  * \param userdata the app-controlled pointer that is passed to iface's
  *                 functions when called.
- * \returns a pointer to the allocated memory on success, or NULL on failure;
+ * \returns a pointer to the allocated memory on success or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -488,7 +488,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
  * \param context a pointer to an SDL_IOStream structure.
  * \param ptr a pointer to a buffer to read data into.
  * \param size the number of bytes to read from the data source.
- * \returns the number of bytes read, or 0 on end of file or other error.
+ * \returns the number of bytes read, or 0 on end of file or other failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -515,7 +515,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr,
  * \param ptr a pointer to a buffer containing data to write.
  * \param size the number of bytes to write.
  * \returns the number of bytes written, which will be less than `size` on
- *          error; call SDL_GetError() for more information.
+ *          failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -535,7 +535,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void
  * \param fmt a printf() style format string.
  * \param ... additional parameters matching % tokens in the `fmt` string, if
  *            any.
- * \returns the number of bytes written, or 0 on error; call SDL_GetError()
+ * \returns the number of bytes written or 0 on failure; call SDL_GetError()
  *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -553,7 +553,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT
  * \param context a pointer to an SDL_IOStream structure.
  * \param fmt a printf() style format string.
  * \param ap a variable argument list.
- * \returns the number of bytes written, or 0 on error; call SDL_GetError()
+ * \returns the number of bytes written or 0 on failure; call SDL_GetError()
  *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -576,7 +576,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
  * \param datasize if not NULL, will store the number of bytes read.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
- * \returns the data, or NULL if there was an error.
+ * \returns the data or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -595,7 +595,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *dat
  *
  * \param file the path to read all available data from.
  * \param datasize if not NULL, will store the number of bytes read.
- * \returns the data, or NULL if there was an error.
+ * \returns the data or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -643,7 +643,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -659,7 +659,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -675,7 +675,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -691,7 +691,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -707,7 +707,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -723,7 +723,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -739,7 +739,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -755,7 +755,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -771,7 +771,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -787,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -803,7 +803,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -819,7 +819,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va
  *
  * \param src the stream from which to read data.
  * \param value a pointer filled in with the data read.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -839,7 +839,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va
  *
  * \param dst the SDL_IOStream to write to.
  * \param value the byte value to write.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -851,7 +851,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
  *
  * \param dst the SDL_IOStream to write to.
  * \param value the byte value to write.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -868,7 +868,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -885,7 +885,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -901,7 +901,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -917,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -934,7 +934,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -951,7 +951,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -967,7 +967,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -983,7 +983,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1000,7 +1000,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1017,7 +1017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1033,7 +1033,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1049,7 +1049,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va
  *
  * \param dst the stream to which data will be written.
  * \param value the data to be written, in native format.
- * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
+ * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_joystick.h

@@ -212,8 +212,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
  *
  * \param count a pointer filled in with the number of joysticks returned.
  * \returns a 0 terminated array of joystick instance IDs which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -364,7 +364,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti
  * for use.
  *
  * \param instance_id the joystick instance ID.
- * \returns a joystick identifier or NULL if an error occurred; call
+ * \returns a joystick identifier or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -470,7 +470,7 @@ typedef struct SDL_VirtualJoystickDesc
  * Attach a new virtual joystick.
  *
  * \param desc joystick description.
- * \returns the joystick instance ID, or 0 if an error occurred; call
+ * \returns the joystick instance ID, or 0 on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_keyboard.h

@@ -75,8 +75,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
  *
  * \param count a pointer filled in with the number of keyboards returned.
  * \returns a 0 terminated array of keyboards instance IDs which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -93,7 +93,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param instance_id the keyboard instance ID.
- * \returns the name of the selected keyboard, or NULL on failure; call
+ * \returns the name of the selected keyboard or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_loadso.h

@@ -56,8 +56,7 @@ extern "C" {
  * Dynamically load a shared object.
  *
  * \param sofile a system-dependent name of the object file.
- * \returns an opaque pointer to the object handle or NULL if there was an
- *          error; call SDL_GetError() for more information.
+ * \returns an opaque pointer to the object handle or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -83,7 +82,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
  *
  * \param handle a valid shared object handle returned by SDL_LoadObject().
  * \param name the name of the function to look up.
- * \returns a pointer to the function or NULL if there was an error; call
+ * \returns a pointer to the function or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_mouse.h

@@ -137,8 +137,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
  *
  * \param count a pointer filled in with the number of mice returned.
  * \returns a 0 terminated array of mouse instance IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -482,7 +482,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
  * You do not have to call SDL_DestroyCursor() on the return value, but it is
  * safe to do so.
  *
- * \returns the default cursor on success or NULL on failure.
+ * \returns the default cursor on success or NULL on failuree; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_pen.h

@@ -156,7 +156,7 @@ typedef enum SDL_PenSubtype
  *
  * \param count the number of pens in the array (number of array elements
  *              minus 1, i.e., not counting the terminator 0).
- * \returns a 0 terminated array of SDL_PenID values, or NULL on error. The
+ * \returns a 0 terminated array of SDL_PenID values, or NULL on failure. The
  *          array must be freed with SDL_free(). On a NULL return,
  *          SDL_GetError() is set.
  *

include/SDL3/SDL_properties.h

@@ -450,7 +450,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
  * \param name the name of the property to query.
  * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
- *          not a float property.
+ *          not a boolean property.
  *
  * \threadsafety It is safe to call this function from any thread.
  *

include/SDL3/SDL_render.h

@@ -327,8 +327,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *render
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param renderer the rendering context.
- * \returns the name of the selected renderer, or NULL if the renderer is
- *          invalid.
+ * \returns the name of the selected renderer, or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1705,7 +1704,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer *renderer);
  * \param renderer the renderer which should draw a point.
  * \param x the x coordinate of the point.
  * \param y the y coordinate of the point.
- * \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.
  *
@@ -1736,7 +1736,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const S
  * \param y1 the y coordinate of the start point.
  * \param x2 the x coordinate of the end point.
  * \param y2 the y coordinate of the end point.
- * \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.
  *
@@ -1766,7 +1767,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD
  * \param renderer the renderer which should draw a rectangle.
  * \param rect a pointer to the destination rectangle, or NULL to outline the
  *             entire rendering target.
- * \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.
  *
@@ -1797,7 +1799,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD
  * \param renderer the renderer which should fill a rectangle.
  * \param rect a pointer to the destination rectangle, or NULL for the entire
  *             rendering target.
- * \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.
  *
@@ -1831,7 +1834,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons
  *                texture.
  * \param dstrect a pointer to the destination rectangle, or NULL for the
  *                entire rendering target.
- * \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.
  *
@@ -1881,7 +1885,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer,
  *                array, if NULL all vertices will be rendered in sequential
  *                order.
  * \param num_indices number of indices.
- * \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.
  *

include/SDL3/SDL_sensor.h

@@ -148,8 +148,8 @@ typedef enum SDL_SensorType
  *
  * \param count a pointer filled in with the number of sensors returned.
  * \returns a 0 terminated array of sensor instance IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -199,7 +199,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i
  * Open a sensor for use.
  *
  * \param instance_id the sensor instance ID.
- * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
+ * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -209,7 +209,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id)
  * Return the SDL_Sensor associated with an instance ID.
  *
  * \param instance_id the sensor instance ID.
- * \returns an SDL_Sensor object.
+ * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -232,7 +232,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param sensor the SDL_Sensor object.
- * \returns the sensor name, or NULL if `sensor` is NULL.
+ * \returns the sensor name or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -263,7 +263,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
  * Get the instance ID of a sensor.
  *
  * \param sensor the SDL_Sensor object to inspect.
- * \returns the sensor instance ID, or 0 if `sensor` is NULL.
+ * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_storage.h

@@ -227,7 +227,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
  * \param storage a storage container to query.
  * \param path the relative path of the file to query.
  * \param length a pointer to be filled with the file's length.
- * \returns 0 if the file could be queried, a negative value otherwise; call
+ * \returns 0 if the file could be queried or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -245,7 +245,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con
  * \param path the relative path of the file to read.
  * \param destination a client-provided buffer to read the file into.
  * \param length the length of the destination buffer.
- * \returns 0 if the file was read, a negative value otherwise; call
+ * \returns 0 if the file was read or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -263,7 +263,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
  * \param path the relative path of the file to write.
  * \param source a client-provided buffer to write from.
  * \param length the length of the source buffer.
- * \returns 0 if the file was written, a negative value otherwise; call
+ * \returns 0 if the file was written or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_surface.h

@@ -128,7 +128,7 @@ typedef struct SDL_Surface
  * \param width the width of the surface.
  * \param height the height of the surface.
  * \param format the SDL_PixelFormat for the new surface's pixel format.
- * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * \returns the new SDL_Surface structure that is created or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
  * \param format the SDL_PixelFormat for the new surface's pixel format.
  * \param pixels a pointer to existing pixel data.
  * \param pitch the number of bytes between each row, including padding.
- * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * \returns the new SDL_Surface structure that is created or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -355,8 +355,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  * \param src the data stream for the surface.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
- * \returns a pointer to a new SDL_Surface structure or NULL if there was an
- *          error; call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_Surface structure or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -373,8 +373,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_b
  * will result in a memory leak.
  *
  * \param file the BMP file to load.
- * \returns a pointer to a new SDL_Surface structure or NULL if there was an
- *          error; call SDL_GetError() for more information.
+ * \returns a pointer to a new SDL_Surface structure or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -688,7 +688,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMo
  * The returned surface should be freed with SDL_DestroySurface().
  *
  * \param surface the surface to duplicate.
- * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
+ * \returns a copy of the surface or NULL on failure; call SDL_GetError() for
  *          more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -710,7 +710,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surfa
  *
  * \param surface the existing SDL_Surface structure to convert.
  * \param format the new pixel format.
- * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * \returns the new SDL_Surface structure that is created or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -733,7 +733,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface
  * \param palette an optional palette to use for indexed formats, may be NULL.
  * \param colorspace the new colorspace.
  * \param props an SDL_PropertiesID with additional color properties, or 0.
- * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * \returns the new SDL_Surface structure that is created or NULL on failure;
  *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_system.h

@@ -162,7 +162,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
  *
  * \param threadID the Unix thread ID to change priority of.
  * \param priority the new, Unix-specific, priority value.
- * \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.
  */
@@ -280,7 +280,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled);
  * rationale being that the SDL headers can avoid including jni.h.
  *
  * \returns a pointer to Java native interface object (JNIEnv) to which the
- *          current thread is attached, or 0 on error.
+ *          current thread is attached, or NULL on failure; call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -304,7 +304,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
  * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
  *
  * \returns the jobject representing the instance of the Activity class of the
- *          Android application, or NULL on error.
+ *          Android application, or NULL on failure; call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -813,7 +813,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle * outTaskQu
  *
  * \param outUserHandle a pointer to be filled in with the default user
  *                      handle.
- * \returns 0 if success, -1 if any error occurs.
+ * \returns 0 if success or a negative error code on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_time.h

@@ -95,8 +95,7 @@ typedef enum SDL_TimeFormat
  *                   format, may be NULL.
  * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
  *                   format, may be NULL.
- * \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.
  */
@@ -107,8 +106,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
  * Jan 1, 1970 in Universal Coordinated Time (UTC).
  *
  * \param ticks the SDL_Time to hold the returned tick count.
- * \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.
  */
@@ -123,8 +121,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
  * \param localTime the resulting SDL_DateTime will be expressed in local time
  *                  if true, otherwise it will be in Universal Coordinated
  *                  Time (UTC).
- * \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.
  */
@@ -138,8 +135,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
  *
  * \param dt the source SDL_DateTime.
  * \param ticks the resulting SDL_Time.
- * \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.
  */
@@ -181,8 +177,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
  *
  * \param year the year.
  * \param month the month [1-12].
- * \returns the number of days in the requested month, otherwise -1; call
- *          SDL_GetError() for more information.
+ * \returns the number of days in the requested month or a negative error code on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -194,8 +189,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
  * \param year the year component of the date.
  * \param month the month component of the date.
  * \param day the day component of the date.
- * \returns the day of year [0-365] if the date is valid, otherwise -1; call
- *          SDL_GetError() for more information.
+ * \returns the day of year [0-365] if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -207,8 +201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
  * \param year the year component of the date.
  * \param month the month component of the date.
  * \param day the day component of the date.
- * \returns a value between 0 and 6 (0 being Sunday) if the date is valid,
- *          otherwise -1; call SDL_GetError() for more information.
+ * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_timer.h

@@ -182,7 +182,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID,
  * \param callback the SDL_TimerCallback function to call when the specified
  *                 `interval` elapses.
  * \param userdata a pointer that is passed to `callback`.
- * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
+ * \returns a timer ID or 0 on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -245,7 +245,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI
  * \param callback the SDL_TimerCallback function to call when the specified
  *                 `interval` elapses.
  * \param userdata a pointer that is passed to `callback`.
- * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
+ * \returns a timer ID or 0 on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_touch.h

@@ -86,8 +86,8 @@ typedef struct SDL_Finger
  * \param count a pointer filled in with the number of devices returned, can
  *              be NULL.
  * \returns a 0 terminated array of touch device IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -99,8 +99,8 @@ extern SDL_DECLSPEC SDL_TouchID *SDLCALL SDL_GetTouchDevices(int *count);
  * The returned string follows the SDL_GetStringRule, and will be automatically freed later.
  *
  * \param touchID the touch device instance ID.
- * \returns touch device name, or NULL on error; call SDL_GetError() for more
- *          details.
+ * \returns touch device name, or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -123,8 +123,8 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
  * \param count a pointer filled in with the number of fingers returned, can
  *              be NULL.
  * \returns a NULL terminated array of SDL_Finger pointers which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_video.h

@@ -394,8 +394,8 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
  * \param count a pointer filled in with the number of displays returned, may
  *              be NULL.
  * \returns a 0 terminated array of display instance IDs which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -533,8 +533,8 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat
  * big on this display, to aid in readability.
  *
  * \param displayID the instance ID of the display to query.
- * \returns the content scale of the display, or 0.0f on error; call
- *          SDL_GetError() for more details.
+ * \returns the content scale of the display, or 0.0f on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -557,8 +557,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
  * \param displayID the instance ID of the display to query.
  * \param count a pointer filled in with the number of display modes returned.
  * \returns a NULL terminated array of display mode pointers which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ *          freed with SDL_free(), or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -584,7 +584,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayMode
  * \param include_high_density_modes boolean to include high density modes in
  *                                   the search.
  * \returns a pointer to the closest display mode equal to or larger than the
- *          desired mode, or NULL on error; call SDL_GetError() for more
+ *          desired mode, or NULL on failure; call SDL_GetError() for more
  *          information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -603,7 +603,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetClosestFullscreenDispl
  * display mode.
  *
  * \param displayID the instance ID of the display to query.
- * \returns a pointer to the desktop display mode or NULL on error; call
+ * \returns a pointer to the desktop display mode or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -622,7 +622,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDesktopDisplayMode(SDL
  * display mode.
  *
  * \param displayID the instance ID of the display to query.
- * \returns a pointer to the desktop display mode or NULL on error; call
+ * \returns a pointer to the desktop display mode or NULL on failure; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -2173,8 +2173,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
  *
  * \param modal_window the window that should be set modal.
  * \param parent_window the parent window for the modal window.
- * \returns 0 on success or a negative error code on failure; 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.
  */
@@ -2583,8 +2582,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value)
  * SDL_GLContext is opaque to the application.
  *
  * \param window the window to associate with the context.
- * \returns the OpenGL context associated with `window` or NULL on error; call
- *          SDL_GetError() for more details.
+ * \returns the OpenGL context associated with `window` or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_vulkan.h

@@ -119,7 +119,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
  * `vkGetInstanceProcAddr =
  * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
  *
- * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
+ * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -149,7 +149,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
  * You should not free the returned array; it is owned by SDL.
  *
  * \param count a pointer filled in with the number of extensions returned.
- * \returns an array of extension name strings on success, NULL on error.
+ * \returns an array of extension name strings on success, NULL on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -173,7 +173,7 @@ extern SDL_DECLSPEC char const* const* SDLCALL SDL_Vulkan_GetInstanceExtensions(
  *                  allocator that creates the surface. Can be NULL.
  * \param surface a pointer to a VkSurfaceKHR handle to output the newly
  *                created surface.
- * \returns 0 on success, -1 on error (check SDL_GetError() for specifics).
+ * \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.
  *