From ce366facaaa2cf13e5178c73d3af18788b0313d2 Mon Sep 17 00:00:00 2001
From: Sylvain <sylvain.becker@gmail.com>
Date: Fri, 10 Feb 2023 22:26:35 +0100
Subject: [PATCH] Add missing \returns, change "return" to "returns" to have
 same naming

---
 include/SDL3/SDL_audio.h    |  5 +++++
 include/SDL3/SDL_gamepad.h  | 21 ++++++++++++++-------
 include/SDL3/SDL_joystick.h |  8 ++++----
 include/SDL3/SDL_keyboard.h |  2 ++
 include/SDL3/SDL_locale.h   |  2 +-
 include/SDL3/SDL_main.h     |  2 +-
 include/SDL3/SDL_metal.h    |  4 ++++
 include/SDL3/SDL_mutex.h    |  2 +-
 include/SDL3/SDL_render.h   | 30 +++++++++++++++---------------
 include/SDL3/SDL_shape.h    |  8 ++++----
 include/SDL3/SDL_stdinc.h   |  5 +++++
 include/SDL3/SDL_surface.h  | 12 +++++++++++-
 include/SDL3/SDL_system.h   |  2 ++
 include/SDL3/SDL_thread.h   |  7 +++++++
 include/SDL3/SDL_touch.h    |  4 ++++
 include/SDL3/SDL_video.h    |  2 +-
 16 files changed, 81 insertions(+), 35 deletions(-)

diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 0d445798b..12c1a18f6 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -768,6 +768,8 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void
  * resample correctly, so this number might be lower than what you expect, or
  * even be zero. Add more data or flush the stream if you need the data now.
  *
+ * \returns the number of converted/resampled bytes available.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
@@ -787,6 +789,9 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
  * audio gaps in the output. Generally this is intended to signal the end of
  * input, so the complete output becomes available.
  *
+ * \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.
  *
  * \sa SDL_CreateAudioStream
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 3f94d402e..4f957e598 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -550,7 +550,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int
  * If the vendor ID isn't available this function returns 0.
  *
  * \param gamepad the gamepad object to query.
- * \return the USB vendor ID, or zero if unavailable.
+ * \returns the USB vendor ID, or zero if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -562,7 +562,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);
  * If the product ID isn't available this function returns 0.
  *
  * \param gamepad the gamepad object to query.
- * \return the USB product ID, or zero if unavailable.
+ * \returns the USB product ID, or zero if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -574,7 +574,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);
  * If the product version isn't available this function returns 0.
  *
  * \param gamepad the gamepad object to query.
- * \return the USB product version, or zero if unavailable.
+ * \returns the USB product version, or zero if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -586,7 +586,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gamepad
  * If the firmware version isn't available this function returns 0.
  *
  * \param gamepad the gamepad object to query.
- * \return the gamepad firmware version, or zero if unavailable.
+ * \returns the gamepad firmware version, or zero if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -598,7 +598,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepa
  * Returns the serial number of the gamepad, or NULL if it is not available.
  *
  * \param gamepad the gamepad object to query.
- * \return the serial number, or NULL if unavailable.
+ * \returns the serial number, or NULL if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -843,6 +843,8 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_Gam
 /**
  * Get the number of touchpads on a gamepad.
  *
+ * \returns number of touchpads
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad);
@@ -851,6 +853,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad);
  * Get the number of supported simultaneous fingers on a touchpad on a game
  * gamepad.
  *
+ * \returns number of supported simultaneous fingers
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepad, int touchpad);
@@ -858,6 +862,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepa
 /**
  * Get the current state of a finger on a touchpad on a 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.
  */
 extern DECLSPEC int SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
@@ -901,7 +908,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad,
  *
  * \param gamepad The gamepad to query
  * \param type The type of sensor to query
- * \return the data rate, or 0.0f if the data rate is not available.
+ * \returns the data rate, or 0.0f if the data rate is not available.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -917,7 +924,7 @@ 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
- * \return 0 or -1 if an error occurred.
+ * \returns 0 or -1 if an error occurred.
  *
  * \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 b2389ccf5..3c619c794 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -793,7 +793,7 @@ extern DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick,
  * \param joystick an SDL_Joystick structure containing joystick information
  * \param axis the axis to query; the axis indices start at index 0
  * \param state Upon return, the initial value is supplied here.
- * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
+ * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -908,7 +908,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U
  * DualShock 4 controller.
  *
  * \param joystick The joystick to query
- * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -918,7 +918,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
  * Query whether a joystick has rumble support.
  *
  * \param joystick The joystick to query
- * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -930,7 +930,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick);
  * Query whether a joystick has rumble support on triggers.
  *
  * \param joystick The joystick to query
- * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  *
diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h
index 3ecc49a0c..78661fcbc 100644
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@@ -293,6 +293,8 @@ extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
 /**
  * Returns if an IME Composite or Candidate window is currently shown.
  *
+ * \returns SDL_TRUE if shown, else SDL_FALSE
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_TextInputShown(void);
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index 61ea54a96..f5896b2cf 100644
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -83,7 +83,7 @@ typedef struct SDL_Locale
  * if possible, and you can call this function again to get an updated copy of
  * preferred locales.
  *
- * \return array of locales, terminated with a locale with a NULL language
+ * \returns array of locales, terminated with a locale with a NULL language
  *         field. Will return NULL on error.
  *
  * \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 06a6beac3..d011e1cf5 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -191,7 +191,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
  *                     argc, char* argv[])
  * \param reserved should be NULL (reserved for future use, will probably be
  *                 platform-specific then)
- * \return the return value from mainFunction: 0 on success, -1 on failure;
+ * \returns the return value from mainFunction: 0 on success, -1 on failure;
  *         SDL_GetError() might have more information on the failure
  *
  * \since This function is available since SDL 3.0.0.
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index 07d83e6ed..fc256b260 100644
--- a/include/SDL3/SDL_metal.h
+++ b/include/SDL3/SDL_metal.h
@@ -58,6 +58,8 @@ typedef void *SDL_MetalView;
  * The returned handle can be casted directly to a NSView or UIView. To access
  * the backing CAMetalLayer, call SDL_Metal_GetLayer().
  *
+ * \returns handle NSView or UIView
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_Metal_DestroyView
@@ -80,6 +82,8 @@ extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
 /**
  * Get a pointer to the backing CAMetalLayer for the given view.
  *
+ * \returns a pointer
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_Metal_CreateView
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index a3616b90c..f406e2210 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -166,7 +166,7 @@ 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
- * \return 0, or -1 on error.
+ * \returns 0, or -1 on error.
  *
  * \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 775ab4c5f..467025961 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -580,7 +580,7 @@ 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.
- * \return 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success, or -1 if the texture is not valid.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -605,7 +605,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *u
  * Get the user-specified pointer associated with a texture
  *
  * \param texture the texture to query.
- * \return the pointer associated with the texture, or NULL if the texture is
+ * \returns the pointer associated with the texture, or NULL if the texture is
  *         not valid.
  *
  * \since This function is available since SDL 3.0.0.
@@ -694,7 +694,7 @@ 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.
- * \return 0 on success, or -1 if the texture is not valid.
+ * \returns 0 on success, or -1 if the texture is not valid.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1161,7 +1161,7 @@ extern 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.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1173,7 +1173,7 @@ 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
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1187,7 +1187,7 @@ extern DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_F
  * \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.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1200,7 +1200,7 @@ 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
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1212,7 +1212,7 @@ extern DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FP
  * \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.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1225,7 +1225,7 @@ 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.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1238,7 +1238,7 @@ extern DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FR
  * \param renderer The renderer which should fill a rectangle.
  * \param rect A pointer to the destination rectangle, or NULL for the entire
  *             rendering target.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1251,7 +1251,7 @@ 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.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1267,7 +1267,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SD
  *                texture.
  * \param dstrect A pointer to the destination rectangle, or NULL for the
  *                entire rendering target.
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1290,7 +1290,7 @@ 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
- * \return 0 on success, or -1 on error
+ * \returns 0 on success, or -1 on error
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1312,7 +1312,7 @@ extern DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL
  *                array, if NULL all vertices will be rendered in sequential
  *                order.
  * \param num_indices Number of indices.
- * \return 0 on success, or -1 if the operation is not supported
+ * \returns 0 on success, or -1 if the operation is not supported
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1342,7 +1342,7 @@ 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)
- * \return 0 on success, or -1 if the operation is not supported
+ * \returns 0 on success, or -1 if the operation is not supported
  *
  * \since This function is available since SDL 3.0.0.
  *
diff --git a/include/SDL3/SDL_shape.h b/include/SDL3/SDL_shape.h
index ea7b89f77..9c5c2cf5d 100644
--- a/include/SDL3/SDL_shape.h
+++ b/include/SDL3/SDL_shape.h
@@ -60,7 +60,7 @@ extern "C" {
  *              ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
  *              ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set,
  *              and ::SDL_WINDOW_FULLSCREEN is always unset.
- * \return the window created, or NULL if window creation failed.
+ * \returns the window created, or NULL if window creation failed.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -72,7 +72,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,un
  * Return whether the given window is a shaped window.
  *
  * \param window The window to query for being shaped.
- * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
+ * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
  *         the window is unshaped or NULL.
  *
  * \since This function is available since SDL 3.0.0.
@@ -116,7 +116,7 @@ typedef struct SDL_WindowShapeMode {
  * \param window The shaped window whose parameters should be set.
  * \param shape A surface encoding the desired shape for the window.
  * \param shape_mode The parameters to set for the shaped window.
- * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
+ * \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
  *         argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
  *         not reference a valid shaped window.
  *
@@ -133,7 +133,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *s
  * \param window The shaped window whose parameters should be retrieved.
  * \param shape_mode An empty shape-mode structure to fill, or NULL to check
  *                   whether the window has a shape.
- * \return 0 if the window has a shape and, provided shape_mode was not NULL,
+ * \returns 0 if the window has a shape and, provided shape_mode was not NULL,
  *         shape_mode has been filled with the mode data,
  *         SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
  *         window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 926f0f88e..7fed1afdf 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -414,6 +414,9 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
 /**
  * Replace SDL's memory allocation functions with a custom set
  *
+ * \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.
  */
 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
@@ -454,6 +457,8 @@ extern DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
 /**
  * Get the number of outstanding (unfreed) allocations
  *
+ * \returns the number of allocations
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index beb969d14..874a9c21e 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -351,7 +351,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface,
  * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
  *
  * \param surface the SDL_Surface structure to query
- * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -795,6 +795,9 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
  * Perform a fast, low quality, stretch blit between two surfaces of the same
  * format.
  *
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
  * Please use SDL_BlitScaled() instead.
  *
  * \since This function is available since SDL 3.0.0.
@@ -807,6 +810,9 @@ extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
 /**
  * Perform bilinear scaling between two surfaces of the same format, 32BPP.
  *
+ * \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.
  */
 extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface *src,
@@ -868,6 +874,8 @@ extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mo
 /**
  * Get the YUV conversion mode
  *
+ * \returns YUV conversion mode
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
@@ -876,6 +884,8 @@ extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
  * Get the YUV conversion mode, returning the correct mode for the resolution
  * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
  *
+ * \returns YUV conversion mode
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 81f557493..b1b7c652a 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -456,6 +456,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int durati
  *
  * \param command user command that must be greater or equal to 0x8000
  * \param param user parameter
+ * \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_thread.h b/include/SDL3/SDL_thread.h
index 3dc89f03b..0d76f28d1 100644
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@@ -116,11 +116,18 @@ typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
 #define SDL_endthread _endthreadex
 #endif
 
+
+/*
+ * \returns SDL_Thread pointer
+ */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
                  pfnSDL_CurrentBeginThread pfnBeginThread,
                  pfnSDL_CurrentEndThread pfnEndThread);
 
+/*
+ * \returns SDL_Thread pointer
+ */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn,
                  const char *name, const size_t stacksize, void *data,
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index 636c6b3db..00d1aaf20 100644
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -99,6 +99,8 @@ extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
  * Get the touch device name as reported from the driver or NULL if the index
  * is invalid.
  *
+ * \returns touch device name
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
@@ -106,6 +108,8 @@ extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
 /**
  * Get the type of the given touch device.
  *
+ * \returns touch device type
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 5f9c4ade8..3c5e6ca9b 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -1458,7 +1458,7 @@ typedef enum
  * \param win the SDL_Window where hit-testing was set on
  * \param area an SDL_Point which should be hit-tested
  * \param data what was passed as `callback_data` to SDL_SetWindowHitTest()
- * \return an SDL_HitTestResult value.
+ * \returns an SDL_HitTestResult value.
  *
  * \sa SDL_SetWindowHitTest
  */