From f8c1fc49d9d1b79b746248ee4855a3a497df8f5f Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 14 Jul 2021 14:15:30 -0400
Subject: [PATCH] doxygen: Fix all the "\returns" so they work as part of
complete sentences.
---
include/SDL.h | 2 +-
include/SDL_audio.h | 2 +-
include/SDL_bits.h | 2 +-
include/SDL_cpuinfo.h | 6 ++---
include/SDL_error.h | 2 +-
include/SDL_events.h | 7 +++--
include/SDL_gamecontroller.h | 10 +++----
include/SDL_mutex.h | 2 +-
include/SDL_render.h | 4 +--
include/SDL_sensor.h | 22 +++++++--------
include/SDL_shape.h | 2 +-
include/SDL_surface.h | 2 +-
include/SDL_system.h | 4 +--
include/SDL_test_assert.h | 2 +-
include/SDL_test_common.h | 10 +++----
include/SDL_test_font.h | 4 +--
include/SDL_test_fuzzer.h | 52 +++++++++++++++++++-----------------
include/SDL_test_harness.h | 4 +--
include/SDL_test_random.h | 2 +-
include/SDL_video.h | 2 +-
include/SDL_vulkan.h | 2 +-
21 files changed, 73 insertions(+), 72 deletions(-)
diff --git a/include/SDL.h b/include/SDL.h
index f4576d619c..633b5f4285 100644
--- a/include/SDL.h
+++ b/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.
*
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 890fcede29..2d12fca2f1 100644
--- a/include/SDL_audio.h
+++ b/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.
diff --git a/include/SDL_bits.h b/include/SDL_bits.h
index 08b59eae39..553b687320 100644
--- a/include/SDL_bits.h
+++ b/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);
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index 9c4c193adf..8fa8a2e8b2 100644
--- a/include/SDL_cpuinfo.h
+++ b/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
diff --git a/include/SDL_error.h b/include/SDL_error.h
index bb200c5fb5..7085871ab9 100644
--- a/include/SDL_error.h
+++ b/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
*/
diff --git a/include/SDL_events.h b/include/SDL_events.h
index 6a04391fea..8b26982fd1 100644
--- a/include/SDL_events.h
+++ b/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.
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 15134bab4c..e5dbaa545c 100644
--- a/include/SDL_gamecontroller.h
+++ b/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);
diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h
index 3b2bf19411..688ab956cb 100644
--- a/include/SDL_mutex.h
+++ b/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
diff --git a/include/SDL_render.h b/include/SDL_render.h
index 21ce63a83d..f0bf8ca56d 100644
--- a/include/SDL_render.h
+++ b/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()
diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h
index 6b2a330c87..189d5e8507 100644
--- a/include/SDL_sensor.h
+++ b/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);
diff --git a/include/SDL_shape.h b/include/SDL_shape.h
index b8c05dbe19..344d09c069 100644
--- a/include/SDL_shape.h
+++ b/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()
*/
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index b6acd477b0..d238f1f4f9 100644
--- a/include/SDL_surface.h
+++ b/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.
*
diff --git a/include/SDL_system.h b/include/SDL_system.h
index 6fea7d30e1..069c3f573e 100644
--- a/include/SDL_system.h
+++ b/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();
diff --git a/include/SDL_test_assert.h b/include/SDL_test_assert.h
index 55e32a41ab..d8e9d7debb 100644
--- a/include/SDL_test_assert.h
+++ b/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);
diff --git a/include/SDL_test_common.h b/include/SDL_test_common.h
index 6a49fa0ab1..ff6c97574a 100644
--- a/include/SDL_test_common.h
+++ b/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);
diff --git a/include/SDL_test_font.h b/include/SDL_test_font.h
index f4912890c2..daa6670c51 100644
--- a/include/SDL_test_font.h
+++ b/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);
diff --git a/include/SDL_test_fuzzer.h b/include/SDL_test_fuzzer.h
index aa0b9a6f70..84278bfb2e 100644
--- a/include/SDL_test_fuzzer.h
+++ b/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);
diff --git a/include/SDL_test_harness.h b/include/SDL_test_harness.h
index 84212a681f..106464cf5a 100644
--- a/include/SDL_test_harness.h
+++ b/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);
diff --git a/include/SDL_test_random.h b/include/SDL_test_random.h
index 2dfbfef5bc..8297f94fbf 100644
--- a/include/SDL_test_random.h
+++ b/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);
diff --git a/include/SDL_video.h b/include/SDL_video.h
index 44a79963dc..876c23244b 100644
--- a/include/SDL_video.h
+++ b/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
diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h
index 5307975179..b8b58c2b86 100644
--- a/include/SDL_vulkan.h
+++ b/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);
(Patch may be truncated, please check the link at the top of this post.)