From f8c1fc49d9d1b79b746248ee4855a3a497df8f5f Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" 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 f4576d619..633b5f428 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 890fcede2..2d12fca2f 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 08b59eae3..553b68732 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 9c4c193ad..8fa8a2e8b 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 bb200c5fb..7085871ab 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 6a04391fe..8b26982fd 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 15134bab4..e5dbaa545 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 3b2bf1941..688ab956c 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 21ce63a83..f0bf8ca56 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`. * * \param renderer The renderer to query - * \returns `id` on success, or NULL if the renderer + * \returns an `id` 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 6b2a330c8..189d5e850 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 b8c05dbe1..344d09c06 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 b6acd477b..d238f1f4f 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 6fea7d30e..069c3f573 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 55e32a41a..d8e9d7deb 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 6a49fa0ab..ff6c97574 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 f4912890c..daa6670c5 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 aa0b9a6f7..84278bfb2 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 84212a681..106464cf5 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 2dfbfef5b..8297f94fb 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 44a79963d..876c23244 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 530797517..b8b58c2b8 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);