doxygen: Fix all the "\returns" so they work as part of complete sentences.

include/SDL.h

@@ -178,7 +178,7 @@ extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
  * Get a mask of the specified subsystems which are currently initialized.
  *
  * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
- * \returns If `flags` is 0 it returns a mask of all initialized subsystems,
+ * \returns a mask of all initialized subsystems if `flags` is 0,
  *          otherwise it returns the initialization status of the specified
  *          subsystems.
  *

include/SDL_audio.h

@@ -1032,7 +1032,7 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da
  * \param dev the device ID from which we will dequeue audio
  * \param data a pointer into where audio data should be copied
  * \param len the number of bytes (not samples!) to which (data) points
- * \returns number of bytes dequeued, which could be less than requested; call
+ * \returns the number of bytes dequeued, which could be less than requested; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 2.0.5.

include/SDL_bits.h

@@ -45,7 +45,7 @@ extern "C" {
  *  with 0. This operation can also be stated as "count leading zeroes" and
  *  "log base 2".
  *
- *  \return Index of the most significant bit, or -1 if the value is 0.
+ *  \return the index of the most significant bit, or -1 if the value is 0.
  */
 #if defined(__WATCOMC__) && defined(__386__)
 extern _inline int _SDL_bsr_watcom (Uint32);

include/SDL_cpuinfo.h

@@ -426,7 +426,7 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
  * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
  * Plan accordingly.
  *
- * \returns Alignment in bytes needed for available, known SIMD instructions.
+ * \returns the alignment in bytes needed for available, known SIMD instructions.
  */
 extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
 
@@ -459,7 +459,7 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
  *
  * \param len The length, in bytes, of the block to allocate. The actual
  *            allocated block might be larger due to padding, etc.
- * \returns Pointer to newly-allocated block, NULL if out of memory.
+ * \returns a pointer to thenewly-allocated block, NULL if out of memory.
  *
  * \sa SDL_SIMDAlignment
  * \sa SDL_SIMDRealloc
@@ -481,7 +481,7 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
  *            allocated block might be larger due to padding, etc. Passing 0
  *            will return a non-NULL pointer, assuming the system isn't out of
  *            memory.
- * \returns Pointer to newly-reallocated block, NULL if out of memory.
+ * \returns a pointer to the newly-reallocated block, NULL if out of memory.
  *
  * \sa SDL_SIMDAlignment
  * \sa SDL_SIMDAlloc

include/SDL_error.h

@@ -106,7 +106,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void);
  * \param errstr A buffer to fill with the last error message that was set
  *                for the current thread
  * \param maxlen The size of the buffer pointed to by the errstr parameter
- * \returns The pointer passed in as the `errstr` parameter.
+ * \returns the pointer passed in as the `errstr` parameter.
  *
  * \sa SDL_GetError
  */

include/SDL_events.h

@@ -909,9 +909,8 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
  * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
  *        or SDL_AddEventWatch, etc
  * \param event the event that triggered the callback
- * \returns Filters return 1 to permit event to be added to the queue, and
- *          0 to disallow it. When used with SDL_AddEventWatch, the return
- *          value is ignored.
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow
+ *          it. When used with SDL_AddEventWatch, the return value is ignored.
  *
  * \sa SDL_SetEventFilter
  * \sa SDL_AddEventWatch
@@ -1074,7 +1073,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
  * 0xFFFFFFFF), but is clearer to write.
  *
  * \param numevents the number of events to be allocated
- * \returns The beginning event number, or (Uint32)-1 if there are not enough
+ * \returns the beginning event number, or (Uint32)-1 if there are not enough
  *          user-defined events left.
  *
  * \since This function is available since SDL 2.0.0.

include/SDL_gamecontroller.h

@@ -388,7 +388,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_Gam
  *  For XInput controllers this returns the XInput user index.
  *
  * \param gamecontroller the game controller object to query.
- * \returns player index for controller, or -1 if it's not available.
+ * \returns the player index for controller, or -1 if it's not available.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
 
@@ -406,7 +406,7 @@ extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController
  * If the vendor ID isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB vendor ID, or zero if unavailable.
+ * \return the USB vendor ID, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
 
@@ -416,7 +416,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *g
  * If the product ID isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB product ID, or zero if unavailable.
+ * \return the USB product ID, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
 
@@ -426,7 +426,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *
  * If the product version isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB product version, or zero if unavailable.
+ * \return the USB product version, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
 
@@ -436,7 +436,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
  * Returns the serial number of the controller, or NULL if it is not available.
  *
  * \param gamecontroller the game controller object to query.
- * \return Serial number, or NULL if unavailable.
+ * \return the serial number, or NULL if unavailable.
  */
 extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
 

include/SDL_mutex.h

@@ -105,7 +105,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
  * don't want to wait for it, and will return to it to try again later.
  *
  * \param mutex the mutex to try to lock
- * \returns return 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
+ * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
  *          SDL_GetError() for more information.
  *
  * \sa SDL_CreateMutex

include/SDL_render.h

@@ -1589,7 +1589,7 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
  * headers, but it can be safely cast to a `CAMetalLayer *`.
  *
  * \param renderer The renderer to query
- * \returns CAMetalLayer* on success, or NULL if the renderer isn't a Metal
+ * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a Metal
  *          renderer
  *
  * \sa SDL_RenderGetMetalCommandEncoder()
@@ -1603,7 +1603,7 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
  * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
  *
  * \param renderer The renderer to query
- * \returns `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
+ * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
  *          isn't a Metal renderer.
  *
  *  \sa SDL_RenderGetMetalLayer()

include/SDL_sensor.h

@@ -140,7 +140,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
 /**
  * Count the number of sensors attached to the system right now.
  *
- * \returns The number of sensors detected.
+ * \returns the number of sensors detected.
  */
 extern DECLSPEC int SDLCALL SDL_NumSensors(void);
 
@@ -148,7 +148,7 @@ extern DECLSPEC int SDLCALL SDL_NumSensors(void);
  * Get the implementation dependent name of a sensor.
  *
  * \param device_index The sensor to obtain name from
- * \returns The sensor name, or NULL if `device_index` is out of range.
+ * \returns the sensor name, or NULL if `device_index` is out of range.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
 
@@ -156,7 +156,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
  * Get the type of a sensor.
  *
  * \param device_index The sensor to get the type from
- * \returns The SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
+ * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
  *          out of range.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
@@ -165,7 +165,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index)
  * Get the platform dependent type of a sensor.
  *
  * \param device_index The sensor to check
- * \returns The sensor platform dependent type, or -1 if `device_index` is out
+ * \returns the sensor platform dependent type, or -1 if `device_index` is out
  *          of range.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
@@ -174,7 +174,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index)
  * Get the instance ID of a sensor.
  *
  * \param device_index The sensor to get instance id from
- * \returns The sensor instance ID, or -1 if `device_index` is out of range.
+ * \returns the sensor instance ID, or -1 if `device_index` is out of range.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
 
@@ -182,7 +182,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_in
  * Open a sensor for use.
  *
  * \param device_index The sensor to open
- * \returns An SDL_Sensor sensor object, or NULL if an error occurred.
+ * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
 
@@ -190,7 +190,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
  * Return the SDL_Sensor associated with an instance id.
  *
  * \param instance_id The sensor from instance id
- * \returns An SDL_Sensor object.
+ * \returns an SDL_Sensor object.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
 
@@ -198,7 +198,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instan
  * Get the implementation dependent name of a sensor
  *
  * \param sensor The SDL_Sensor object
- * \returns The sensor name, or NULL if `sensor` is NULL.
+ * \returns the sensor name, or NULL if `sensor` is NULL.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
 
@@ -206,7 +206,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
  * Get the type of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
+ * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
  *          NULL.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
@@ -215,7 +215,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
  * Get the platform dependent type of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The sensor platform dependent type, or -1 if `sensor` is NULL.
+ * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
 
@@ -223,7 +223,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
  * Get the instance ID of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The sensor instance ID, or -1 if `sensor` is NULL.
+ * \returns the sensor instance ID, or -1 if `sensor` is NULL.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
 

include/SDL_shape.h

@@ -59,7 +59,7 @@ extern "C" {
  *               ::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.
+ *  \return the window created, or NULL if window creation failed.
  *
  *  \sa SDL_DestroyWindow()
  */

include/SDL_surface.h

@@ -714,7 +714,7 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
  *  in \c srcrect and \c dstrect after all clipping is performed.
  *
- *  \return If the blit is successful, it returns 0, otherwise it returns -1.
+ *  \returns 0 if the blit is successful, otherwise it returns -1.
  *
  *  The blit function should not be called on a locked surface.
  *

include/SDL_system.h

@@ -218,7 +218,7 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
  * - API level 11: Android 3.0
  * - API level 10: Android 2.3.3
  *
- * \returns Android API level.
+ * \returns the Android API level.
  */
 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
 
@@ -439,7 +439,7 @@ extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathT
 /**
  * Detects the device family of WinRT plattform at runtime.
  *
- * \returns A value from the SDL_WinRT_DeviceFamily enum.
+ * \returns a value from the SDL_WinRT_DeviceFamily enum.
  */
 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
 

include/SDL_test_assert.h

@@ -66,7 +66,7 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
  * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
  * \param assertDescription Message to log with the assert describing it.
  *
- * \returns Returns the assertCondition so it can be used to externally to break execution flow if desired.
+ * \returns the assertCondition so it can be used to externally to break execution flow if desired.
  */
 int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
 

include/SDL_test_common.h

@@ -129,7 +129,7 @@ extern "C" {
  * \param argv Array of command line parameters
  * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
  *
- * \returns Returns a newly allocated common state object.
+ * \returns a newly allocated common state object.
  */
 SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
 
@@ -139,7 +139,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
  * \param state The common state describing the test window to create.
  * \param index The index of the argument to process in argv[].
  *
- * \returns The number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
+ * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
  */
 int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
 
@@ -167,7 +167,7 @@ void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, cons
  *  those strings' memory is freed and can no longer be used.
  *
  * \param state The common state describing the test window to create.
- * \returns String with usage information
+ * \returns a string with usage information
  */
 const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
 
@@ -176,7 +176,7 @@ const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
  *
  * \param state The common state describing the test window to create.
  *
- * \returns True if initialization succeeded, false otherwise
+ * \returns SDL_TRUE if initialization succeeded, false otherwise
  */
 SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
 
@@ -187,7 +187,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
  * \param argc argc, as supplied to SDL_main
  * \param argv argv, as supplied to SDL_main
  *
- * \returns False if app should quit, true otherwise.
+ * \returns SDL_FALSE if app should quit, true otherwise.
  */
 SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv);
 

include/SDL_test_font.h

@@ -48,7 +48,7 @@ extern "C" {
  *  \param y The Y coordinate of the upper left corner of the character.
  *  \param c The character to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
 
@@ -60,7 +60,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
  *  \param y The Y coordinate of the upper left corner of the string.
  *  \param s The string to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s);
 

include/SDL_test_fuzzer.h

@@ -66,14 +66,14 @@ void SDLTest_FuzzerInit(Uint64 execKey);
 /**
  * Returns a random Uint8
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint8 SDLTest_RandomUint8(void);
 
 /**
  * Returns a random Sint8
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint8 SDLTest_RandomSint8(void);
 
@@ -81,14 +81,14 @@ Sint8 SDLTest_RandomSint8(void);
 /**
  * Returns a random Uint16
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint16 SDLTest_RandomUint16(void);
 
 /**
  * Returns a random Sint16
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint16 SDLTest_RandomSint16(void);
 
@@ -96,7 +96,7 @@ Sint16 SDLTest_RandomSint16(void);
 /**
  * Returns a random integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Sint32 SDLTest_RandomSint32(void);
 
@@ -104,14 +104,14 @@ Sint32 SDLTest_RandomSint32(void);
 /**
  * Returns a random positive integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint32 SDLTest_RandomUint32(void);
 
 /**
  * Returns random Uint64.
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint64 SDLTest_RandomUint64(void);
 
@@ -119,28 +119,28 @@ Uint64 SDLTest_RandomUint64(void);
 /**
  * Returns random Sint64.
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint64 SDLTest_RandomSint64(void);
 
 /**
- * \returns random float in range [0.0 - 1.0[
+ * \returns a random float in range [0.0 - 1.0]
  */
 float SDLTest_RandomUnitFloat(void);
 
 /**
- * \returns random double in range [0.0 - 1.0[
+ * \returns a random double in range [0.0 - 1.0]
  */
 double SDLTest_RandomUnitDouble(void);
 
 /**
- * \returns random float.
+ * \returns a random float.
  *
  */
 float SDLTest_RandomFloat(void);
 
 /**
- * \returns random double.
+ * \returns a random double.
  *
  */
 double SDLTest_RandomDouble(void);
@@ -162,7 +162,7 @@ double SDLTest_RandomDouble(void);
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
 
@@ -183,7 +183,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
 
@@ -204,7 +204,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
 
@@ -225,7 +225,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
 
@@ -246,7 +246,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT8_MIN with error set
  */
 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
 
@@ -268,7 +268,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT16_MIN with error set
  */
 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
 
@@ -289,7 +289,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT32_MIN with error set
  */
 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
 
@@ -310,7 +310,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT64_MIN with error set
  */
 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
 
@@ -324,7 +324,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL
  * \param min Minimum inclusive value of returned random number
  * \param max Maximum inclusive value of returned random number
  *
- * \returns Generated random integer in range
+ * \returns a generated random integer in range
  */
 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
 
@@ -336,7 +336,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
  *
  * Note: Returned string needs to be deallocated.
  *
- * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiString(void);
 
@@ -350,7 +350,7 @@ char * SDLTest_RandomAsciiString(void);
  *
  * \param maxLength The maximum length of the generated string.
  *
- * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
 
@@ -364,12 +364,14 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
  *
  * \param size The length of the generated string
  *
- * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringOfSize(int size);
 
 /**
- * Returns the invocation count for the fuzzer since last ...FuzzerInit.
+ * Get the invocation count for the fuzzer since last ...FuzzerInit.
+ *
+ * \returns the invocation count.
  */
 int SDLTest_GetFuzzerInvocationCount(void);
 

include/SDL_test_harness.h

@@ -105,7 +105,7 @@ typedef struct SDLTest_TestSuiteReference {
  *
  * \param length The length of the seed string to generate
  *
- * \returns The generated seed string
+ * \returns the generated seed string
  */
 char *SDLTest_GenerateRunSeed(const int length);
 
@@ -118,7 +118,7 @@ char *SDLTest_GenerateRunSeed(const int length);
  * \param filter Filter specification. NULL disables. Case sensitive.
  * \param testIterations Number of iterations to run each test case.
  *
- * \returns Test run result; 0 when all tests passed, 1 if any tests failed.
+ * \returns the test run result: 0 when all tests passed, 1 if any tests failed.
  */
 int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations);
 

include/SDL_test_random.h

@@ -98,7 +98,7 @@ extern "C" {
  *
  *  \param rndContext     pointer to context structure
  *
- *  \returns A random number (32bit unsigned integer)
+ *  \returns a random number (32bit unsigned integer)
  *
  */
  unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext);

include/SDL_video.h

@@ -1244,7 +1244,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
  * Get a window's mouse grab mode.
  *
  * \param window the window to query
- * \returns This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
+ * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
  *
  * \sa SDL_SetWindowKeyboardGrab
  * \sa SDL_GetWindowGrab

include/SDL_vulkan.h

@@ -114,7 +114,7 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
  * This should be called after either calling SDL_Vulkan_LoadLibrary()
  * or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
  *
- * \returns The function pointer for `vkGetInstanceProcAddr` or NULL on error.
+ * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
  */
 extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);