Updated headers with latest wikiheaders tweaks.

include/SDL3/SDL_assert.h

@@ -234,11 +234,11 @@ typedef struct SDL_AssertData
  *
  * Use the SDL_assert* macros instead.
  *
- * \param data assert data structure
- * \param func function name
- * \param file file name
- * \param line line number
- * \returns assert state
+ * \param data assert data structure.
+ * \param func function name.
+ * \param file file name.
+ * \param line line number.
+ * \returns assert state.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
  * Please refer to your platform's documentation for how to set it!
  *
- * \param condition boolean value to test
+ * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
  */
@@ -339,7 +339,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
  * Please refer to your platform's documentation for how to set it!
  *
- * \param condition boolean value to test
+ * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
  */
@@ -369,7 +369,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
  * Please refer to your platform's documentation for how to set it!
  *
- * \param condition boolean value to test
+ * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
  */
@@ -415,7 +415,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * Note that SDL_ASSERT is an _environment variable_ and not an SDL hint!
  * Please refer to your platform's documentation for how to set it!
  *
- * \param condition boolean value to test
+ * \param condition boolean value to test.
  *
  * \since This macro is available since SDL 3.0.0.
  */
@@ -426,8 +426,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
  * A callback that fires when an SDL assertion fails.
  *
  * \param data a pointer to the SDL_AssertData structure corresponding to the
- *             current assertion
- * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
+ *             current assertion.
+ * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler().
  * \returns an SDL_AssertState value indicating how to handle the failure.
  *
  * \since This datatype is available since SDL 3.0.0.
@@ -449,8 +449,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
  * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
  *
  * \param handler the SDL_AssertionHandler function to call when an assertion
- *                fails or NULL for the default handler
- * \param userdata a pointer that is passed to `handler`
+ *                fails or NULL for the default handler.
+ * \param userdata a pointer that is passed to `handler`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -491,7 +491,7 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(
  * data, it is safe to pass a NULL pointer to this function to ignore it.
  *
  * \param puserdata pointer which is filled with the "userdata" pointer that
- *                  was passed to SDL_SetAssertionHandler()
+ *                  was passed to SDL_SetAssertionHandler().
  * \returns the SDL_AssertionHandler that is called when an assert triggers.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_atomic.h

@@ -87,7 +87,7 @@ typedef int SDL_SpinLock;
  * ***Please note that spinlocks are dangerous if you don't know what you're
  * doing. Please be careful using any sort of spinlock!***
  *
- * \param lock a pointer to a lock variable
+ * \param lock a pointer to a lock variable.
  * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
  *          held.
  *
@@ -104,7 +104,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock);
  * ***Please note that spinlocks are dangerous if you don't know what you're
  * doing. Please be careful using any sort of spinlock!***
  *
- * \param lock a pointer to a lock variable
+ * \param lock a pointer to a lock variable.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -121,7 +121,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock);
  * ***Please note that spinlocks are dangerous if you don't know what you're
  * doing. Please be careful using any sort of spinlock!***
  *
- * \param lock a pointer to a lock variable
+ * \param lock a pointer to a lock variable.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -333,9 +333,9 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt;
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to an SDL_AtomicInt variable to be modified
- * \param oldval the old value
- * \param newval the new value
+ * \param a a pointer to an SDL_AtomicInt variable to be modified.
+ * \param oldval the old value.
+ * \param newval the new value.
  * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -354,8 +354,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a,
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to an SDL_AtomicInt variable to be modified
- * \param v the desired value
+ * \param a a pointer to an SDL_AtomicInt variable to be modified.
+ * \param v the desired value.
  * \returns the previous value of the atomic variable.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -372,7 +372,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v);
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to an SDL_AtomicInt variable
+ * \param a a pointer to an SDL_AtomicInt variable.
  * \returns the current value of an atomic variable.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -391,8 +391,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a);
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to an SDL_AtomicInt variable to be modified
- * \param v the desired value to add
+ * \param a a pointer to an SDL_AtomicInt variable to be modified.
+ * \param v the desired value to add.
  * \returns the previous value of the atomic variable.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -430,7 +430,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
  *
  * \param a a pointer to an SDL_AtomicInt to increment.
  * \returns SDL_TRUE if the variable reached zero after decrementing,
- *          SDL_FALSE otherwise
+ *          SDL_FALSE otherwise.
  *
  * \since This macro is available since SDL 3.0.0.
  *
@@ -445,9 +445,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to a pointer
- * \param oldval the old pointer value
- * \param newval the new pointer value
+ * \param a a pointer to a pointer.
+ * \param oldval the old pointer value.
+ * \param newval the new pointer value.
  * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -466,8 +466,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to a pointer
- * \param v the desired pointer value
+ * \param a a pointer to a pointer.
+ * \param v the desired pointer value.
  * \returns the previous value of the pointer.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -485,7 +485,7 @@ extern SDL_DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
  *
- * \param a a pointer to a pointer
+ * \param a a pointer to a pointer.
  * \returns the current value of a pointer.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_audio.h

@@ -141,8 +141,8 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
  *
- * \param x an SDL_AudioFormat value
- * \returns data size in bits
+ * \param x an SDL_AudioFormat value.
+ * \returns data size in bits.
  *
  * \threadsafety It is safe to call this macro from any thread.
  *
@@ -155,8 +155,8 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
  *
- * \param x an SDL_AudioFormat value
- * \returns data size in bytes
+ * \param x an SDL_AudioFormat value.
+ * \returns data size in bytes.
  *
  * \threadsafety It is safe to call this macro from any thread.
  *
@@ -169,7 +169,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is floating point, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -183,7 +183,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is bigendian, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -197,7 +197,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is littleendian, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -211,7 +211,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is signed, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -225,7 +225,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is integer, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -239,7 +239,7 @@ typedef Uint16 SDL_AudioFormat;
  *
  * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
  *
- * \param x an SDL_AudioFormat value
+ * \param x an SDL_AudioFormat value.
  * \returns non-zero if format is unsigned, zero otherwise.
  *
  * \threadsafety It is safe to call this macro from any thread.
@@ -382,7 +382,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
  * The returned string follows the SDL_GetStringRule.
  *
  * \param index the index of the audio driver; the value ranges from 0 to
- *              SDL_GetNumAudioDrivers() - 1
+ *              SDL_GetNumAudioDrivers() - 1.
  * \returns the name of the audio driver at the requested index, or NULL if an
  *          invalid index was specified.
  *
@@ -512,8 +512,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID
  * playback timing. Most apps do not need this.
  *
  * \param devid the instance ID of the device to query.
- * \param spec On return, will be filled with device details.
- * \param sample_frames Pointer to store device buffer size, in sample frames.
+ * \param spec on return, will be filled with device details.
+ * \param sample_frames pointer to store device buffer size, in sample frames.
  *                      Can be NULL.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
@@ -618,7 +618,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic
  * Physical devices can not be paused or unpaused, only logical devices
  * created through SDL_OpenAudioDevice() can be.
  *
- * \param dev a device opened by SDL_OpenAudioDevice()
+ * \param dev a device opened by SDL_OpenAudioDevice().
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -646,7 +646,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
  * Physical devices can not be paused or unpaused, only logical devices
  * created through SDL_OpenAudioDevice() can be.
  *
- * \param dev a device opened by SDL_OpenAudioDevice()
+ * \param dev a device opened by SDL_OpenAudioDevice().
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -669,7 +669,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
  * created through SDL_OpenAudioDevice() can be. Physical and invalid device
  * IDs will report themselves as unpaused here.
  *
- * \param dev a device opened by SDL_OpenAudioDevice()
+ * \param dev a device opened by SDL_OpenAudioDevice().
  * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -692,7 +692,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
  * supplied if terminating immediately afterwards.
  *
  * \param devid an audio device id previously returned by
- *              SDL_OpenAudioDevice()
+ *              SDL_OpenAudioDevice().
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -725,7 +725,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
  *
  * \param devid an audio device to bind a stream to.
  * \param streams an array of audio streams to unbind.
- * \param num_streams Number streams listed in the `streams` array.
+ * \param num_streams number streams listed in the `streams` array.
  * \returns 0 on success, -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -770,7 +770,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL
  * Unbinding a stream that isn't bound to a device is a legal no-op.
  *
  * \param streams an array of audio streams to unbind.
- * \param num_streams Number streams listed in the `streams` array.
+ * \param num_streams number streams listed in the `streams` array.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -819,8 +819,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
 /**
  * Create a new audio stream.
  *
- * \param src_spec The format details of the input audio
- * \param dst_spec The format details of the output audio
+ * \param src_spec the format details of the input audio.
+ * \param dst_spec the format details of the output audio.
  * \returns a new audio stream on success, or NULL on failure.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -840,7 +840,7 @@ extern SDL_DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_Aud
 /**
  * Get the properties associated with an audio stream.
  *
- * \param stream the SDL_AudioStream to query
+ * \param stream the SDL_AudioStream to query.
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -855,8 +855,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
  * Query the current format of an audio stream.
  *
  * \param stream the SDL_AudioStream to query.
- * \param src_spec Where to store the input audio format; ignored if NULL.
- * \param dst_spec Where to store the output audio format; ignored if NULL.
+ * \param src_spec where to store the input audio format; ignored if NULL.
+ * \param dst_spec where to store the output audio format; ignored if NULL.
  * \returns 0 on success, or -1 on error.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
@@ -881,10 +881,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
  * next sound file, and start putting that new data while the previous sound
  * file is still queued, and everything will still play back correctly.
  *
- * \param stream The stream the format is being changed
- * \param src_spec The new format of the audio input; if NULL, it is not
+ * \param stream the stream the format is being changed.
+ * \param src_spec the new format of the audio input; if NULL, it is not
  *                 changed.
- * \param dst_spec The new format of the audio output; if NULL, it is not
+ * \param dst_spec the new format of the audio output; if NULL, it is not
  *                 changed.
  * \returns 0 on success, or -1 on error.
  *
@@ -904,7 +904,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream
  * Get the frequency ratio of an audio stream.
  *
  * \param stream the SDL_AudioStream to query.
- * \returns the frequency ratio of the stream, or 0.0 on error
+ * \returns the frequency ratio of the stream, or 0.0 on error.
  *
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running.
@@ -927,8 +927,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
  * This is applied during SDL_GetAudioStreamData, and can be continuously
  * changed to create various effects.
  *
- * \param stream The stream the frequency ratio is being changed
- * \param ratio The frequency ratio. 1.0 is normal speed. Must be between 0.01
+ * \param stream the stream the frequency ratio is being changed.
+ * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
  *              and 100.
  * \returns 0 on success, or -1 on error.
  *
@@ -953,9 +953,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
  * different than SDL2, where data was converted during the Put call and the
  * Get call would just dequeue the previously-converted data.
  *
- * \param stream The stream the audio data is being added to
- * \param buf A pointer to the audio data to add
- * \param len The number of bytes to write to the stream
+ * \param stream the stream the audio data is being added to.
+ * \param buf a pointer to the audio data to add.
+ * \param len the number of bytes to write to the stream.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -984,10 +984,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
  * is different than SDL2, where that work was done while inputting new data
  * to the stream and requesting the output just copied the converted data.
  *
- * \param stream The stream the audio is being requested from
- * \param buf A buffer to fill with audio data
- * \param len The maximum number of bytes to fill
- * \returns the number of bytes read from the stream, or -1 on error
+ * \param stream the stream the audio is being requested from.
+ * \param buf a buffer to fill with audio data.
+ * \param len the maximum number of bytes to fill.
+ * \returns the number of bytes read from the stream, or -1 on error.
  *
  * \threadsafety It is safe to call this function from any thread, but if the
  *               stream has a callback set, the caller might need to manage
@@ -1014,7 +1014,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream,
  * SDL_GetAudioStreamData before this function's return value is no longer
  * clamped.
  *
- * \param stream The audio stream to query
+ * \param stream the audio stream to query.
  * \returns the number of converted/resampled bytes available.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -1046,7 +1046,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str
  * SDL_GetAudioStreamData before this function's return value is no longer
  * clamped.
  *
- * \param stream The audio stream to query
+ * \param stream the audio stream to query.
  * \returns the number of bytes queued.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -1067,7 +1067,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream
  * audio gaps in the output. Generally this is intended to signal the end of
  * input, so the complete output becomes available.
  *
- * \param stream The audio stream to flush
+ * \param stream the audio stream to flush.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1085,7 +1085,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
  * This drops any queued data, so there will be nothing to read from the
  * stream until more is added.
  *
- * \param stream The audio stream to clear
+ * \param stream the audio stream to clear.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1112,7 +1112,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
  * audio streams. This might be useful while a game is paused, or a level is
  * loading, etc.
  *
- * \param stream The audio stream associated with the audio device to pause
+ * \param stream the audio stream associated with the audio device to pause.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1132,7 +1132,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stre
  * previously been paused. Once unpaused, any bound audio streams will begin
  * to progress again, and audio can be generated.
  *
- * \param stream The audio stream associated with the audio device to resume
+ * \param stream the audio stream associated with the audio device to resume.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1160,7 +1160,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *str
  * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
  * all the same attributes (recursive locks are allowed, etc).
  *
- * \param stream The audio stream to lock.
+ * \param stream the audio stream to lock.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1178,7 +1178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
  *
  * This unlocks an audio stream after a call to SDL_LockAudioStream.
  *
- * \param stream The audio stream to unlock.
+ * \param stream the audio stream to unlock.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1212,12 +1212,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
  * appropriate, but the system goes on with the data currently available to it
  * if this callback does nothing.
  *
- * \param stream The SDL audio stream associated with this callback.
- * \param additional_amount The amount of data, in bytes, that is needed right
+ * \param stream the SDL audio stream associated with this callback.
+ * \param additional_amount the amount of data, in bytes, that is needed right
  *                          now.
- * \param total_amount The total amount of data requested, in bytes, that is
+ * \param total_amount the total amount of data requested, in bytes, that is
  *                     requested or available.
- * \param userdata An opaque pointer provided by the app for their personal
+ * \param userdata an opaque pointer provided by the app for their personal
  *                 use.
  *
  * \threadsafety This callbacks may run from any thread, so if you need to
@@ -1338,7 +1338,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *s
  * device that was opened alongside this stream's creation will be closed,
  * too.
  *
- * \param stream The audio stream to destroy.
+ * \param stream the audio stream to destroy.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1390,11 +1390,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
  * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
  *              SDL_AUDIO_DEVICE_DEFAULT_CAPTURE.
  * \param spec the audio stream's data format. Can be NULL.
- * \param callback A callback where the app will provide new data for
+ * \param callback a callback where the app will provide new data for
  *                 playback, or receive new data for capture. Can be NULL, in
  *                 which case the app will need to call SDL_PutAudioStreamData
  *                 or SDL_GetAudioStreamData as necessary.
- * \param userdata App-controlled pointer passed to callback. Can be NULL.
+ * \param userdata app-controlled pointer passed to callback. Can be NULL.
  *                 Ignored if callback is NULL.
  * \returns an audio stream on success, ready to use. NULL on error; call
  *          SDL_GetError() for more information. When done with this stream,
@@ -1485,9 +1485,9 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
  *
  * Setting a NULL callback function disables any previously-set callback.
  *
- * \param devid The ID of an opened audio device.
- * \param callback A callback function to be called. Can be NULL.
- * \param userdata App-controlled pointer passed to callback. Can be NULL.
+ * \param devid the ID of an opened audio device.
+ * \param callback a callback function to be called. Can be NULL.
+ * \param userdata app-controlled pointer passed to callback. Can be NULL.
  * \returns zero on success, -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -1549,15 +1549,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID de
  * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
  * ```
  *
- * \param src The data source for the WAVE data
- * \param closeio If SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
- *                even in the case of an error
- * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
- *             data's format details on successful return
- * \param audio_buf A pointer filled with the audio data, allocated by the
- *                  function
- * \param audio_len A pointer filled with the length of the audio data buffer
- *                  in bytes
+ * \param src the data source for the WAVE data.
+ * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
+ *                even in the case of an error.
+ * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
+ *             data's format details on successful return.
+ * \param audio_buf a pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len a pointer filled with the length of the audio data buffer
+ *                  in bytes.
  * \returns 0 on success. `audio_buf` will be filled with a pointer to an
  *          allocated buffer containing the audio data, and `audio_len` is
  *          filled with the length of that audio buffer in bytes.
@@ -1589,13 +1589,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool clos
  * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
  * ```
  *
- * \param path The file path of the WAV file to open.
- * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
+ * \param path the file path of the WAV file to open.
+ * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
  *             data's format details on successful return.
- * \param audio_buf A pointer filled with the audio data, allocated by the
+ * \param audio_buf a pointer filled with the audio data, allocated by the
  *                  function.
- * \param audio_len A pointer filled with the length of the audio data buffer
- *                  in bytes
+ * \param audio_len a pointer filled with the length of the audio data buffer
+ *                  in bytes.
  * \returns 0 on success. `audio_buf` will be filled with a pointer to an
  *          allocated buffer containing the audio data, and `audio_len` is
  *          filled with the length of that audio buffer in bytes.
@@ -1637,13 +1637,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * sp
  * SDL_MixAudio() is really only needed when you're mixing a single audio
  * stream with a volume adjustment.
  *
- * \param dst the destination for the mixed audio
- * \param src the source audio buffer to be mixed
+ * \param dst the destination for the mixed audio.
+ * \param src the source audio buffer to be mixed.
  * \param format the SDL_AudioFormat structure representing the desired audio
- *               format
- * \param len the length of the audio buffer in bytes
+ *               format.
+ * \param len the length of the audio buffer in bytes.
  * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
- *               audio volume
+ *               audio volume.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1669,14 +1669,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_MixAudio(Uint8 * dst,
  * use, so it's also less efficient than using one directly, if you need to
  * convert multiple times.
  *
- * \param src_spec The format details of the input audio
- * \param src_data The audio data to be converted
- * \param src_len The len of src_data
- * \param dst_spec The format details of the output audio
- * \param dst_data Will be filled with a pointer to converted audio data,
+ * \param src_spec the format details of the input audio.
+ * \param src_data the audio data to be converted.
+ * \param src_len the len of src_data.
+ * \param dst_spec the format details of the output audio.
+ * \param dst_data will be filled with a pointer to converted audio data,
  *                 which should be freed with SDL_free(). On error, it will be
  *                 NULL.
- * \param dst_len Will be filled with the len of dst_data
+ * \param dst_len will be filled with the len of dst_data.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_bits.h

@@ -60,7 +60,7 @@ extern __inline int _SDL_bsr_watcom(Uint32);
  * embedded in the calling program and the linker and dynamic loader will not
  * be able to find this function inside SDL itself).
  *
- * \param x the 32-bit value to examine
+ * \param x the 32-bit value to examine.
  * \returns the index of the most significant bit, or -1 if the value is 0.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -128,7 +128,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x)
  * embedded in the calling program and the linker and dynamic loader will not
  * be able to find this function inside SDL itself).
  *
- * \param x the 32-bit value to examine
+ * \param x the 32-bit value to examine.
  * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.

include/SDL3/SDL_blendmode.h

@@ -168,18 +168,18 @@ typedef enum SDL_BlendFactor
  * case.
  *
  * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
- *                       blue components of the source pixels
+ *                       blue components of the source pixels.
  * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
- *                       blue components of the destination pixels
+ *                       blue components of the destination pixels.
  * \param colorOperation the SDL_BlendOperation used to combine the red,
  *                       green, and blue components of the source and
- *                       destination pixels
+ *                       destination pixels.
  * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
- *                       the source pixels
+ *                       the source pixels.
  * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
- *                       the destination pixels
+ *                       the destination pixels.
  * \param alphaOperation the SDL_BlendOperation used to combine the alpha
- *                       component of the source and destination pixels
+ *                       component of the source and destination pixels.
  * \returns an SDL_BlendMode that represents the chosen factors and
  *          operations.
  *

include/SDL3/SDL_camera.h

@@ -137,7 +137,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
  * The returned string follows the SDL_GetStringRule.
  *
  * \param index the index of the camera driver; the value ranges from 0 to
- *              SDL_GetNumCameraDrivers() - 1
+ *              SDL_GetNumCameraDrivers() - 1.
  * \returns the name of the camera driver at the requested index, or NULL if
  *          an invalid index was specified.
  *
@@ -232,7 +232,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the camera device instance ID
+ * \param instance_id the camera device instance ID.
  * \returns a human-readable device name, or NULL on error; call
  *          SDL_GetError() for more information.
  *
@@ -252,7 +252,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDeviceName(SDL_CameraDevic
  * points towards the user, for taking "selfies") and cameras on the back (for
  * filming in the direction the user is facing).
  *
- * \param instance_id the camera device instance ID
+ * \param instance_id the camera device instance ID.
  * \returns the position of the camera on the system hardware.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -294,8 +294,8 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraDevicePosition(SDL_C
  * where the user previously permitted access), the approval event might come
  * immediately, but it might come seconds, minutes, or hours later!
  *
- * \param instance_id the camera device instance ID
- * \param spec The desired format for data the device will provide. Can be
+ * \param instance_id the camera device instance ID.
+ * \param spec the desired format for data the device will provide. Can be
  *             NULL.
  * \returns device, or NULL on failure; call SDL_GetError() for more
  *          information.
@@ -329,7 +329,7 @@ extern SDL_DECLSPEC SDL_Camera *SDLCALL SDL_OpenCameraDevice(SDL_CameraDeviceID
  * If a camera is declined, there's nothing to be done but call
  * SDL_CloseCamera() to dispose of it.
  *
- * \param camera the opened camera device to query
+ * \param camera the opened camera device to query.
  * \returns -1 if user denied access to the camera, 1 if user approved access,
  *          0 if no decision has been made yet.
  *
@@ -345,7 +345,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera)
 /**
  * Get the instance ID of an opened camera.
  *
- * \param camera an SDL_Camera to query
+ * \param camera an SDL_Camera to query.
  * \returns the instance ID of the specified camera on success or 0 on
  *          failure; call SDL_GetError() for more information.
  *
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC SDL_CameraDeviceID SDLCALL SDL_GetCameraInstanceID(SDL_Camer
 /**
  * Get the properties associated with an opened camera.
  *
- * \param camera the SDL_Camera obtained from SDL_OpenCameraDevice()
+ * \param camera the SDL_Camera obtained from SDL_OpenCameraDevice().
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -385,8 +385,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera
  * (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
  * occasionally until it returns non-zero.
  *
- * \param camera opened camera device
- * \param spec The SDL_CameraSpec to be initialized by this function.
+ * \param camera opened camera device.
+ * \param spec the SDL_CameraSpec to be initialized by this function.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -427,7 +427,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_Came
  * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
  * occasionally until it returns non-zero.
  *
- * \param camera opened camera device
+ * \param camera opened camera device.
  * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
  *                    error. Can be NULL.
  * \returns a new frame of video on success, NULL if none is currently
@@ -458,8 +458,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam
  * The app should not use the surface again after calling this function;
  * assume the surface is freed and the pointer is invalid.
  *
- * \param camera opened camera device
- * \param frame The video frame surface to release.
+ * \param camera opened camera device.
+ * \param frame the video frame surface to release.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_S
  * Use this function to shut down camera processing and close the camera
  * device.
  *
- * \param camera opened camera device
+ * \param camera opened camera device.
  *
  * \threadsafety It is safe to call this function from any thread, but no
  *               thread may reference `device` once this function is called.

include/SDL3/SDL_clipboard.h

@@ -45,7 +45,7 @@ extern "C" {
 /**
  * Put UTF-8 text into the clipboard.
  *
- * \param text the text to store in the clipboard
+ * \param text the text to store in the clipboard.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -89,7 +89,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
 /**
  * Put UTF-8 text into the primary selection.
  *
- * \param text the text to store in the primary selection
+ * \param text the text to store in the primary selection.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -141,9 +141,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
  * clipboard is cleared or new data is set. The clipboard is automatically
  * cleared in SDL_Quit().
  *
- * \param userdata A pointer to provided user data
- * \param mime_type The requested mime-type
- * \param size A pointer filled in with the length of the returned data
+ * \param userdata a pointer to provided user data.
+ * \param mime_type the requested mime-type.
+ * \param size a pointer filled in with the length of the returned data.
  * \returns a pointer to the data for the provided mime-type. Returning NULL
  *          or setting length to 0 will cause no data to be sent to the
  *          "receiver". It is up to the receiver to handle this. Essentially
@@ -161,7 +161,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c
  * Callback function that will be called when the clipboard is cleared, or new
  * data is set.
  *
- * \param userdata A pointer to provided user data
+ * \param userdata a pointer to provided user data.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -181,13 +181,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
  * not need to be null terminated (e.g. you can directly copy a portion of a
  * document)
  *
- * \param callback A function pointer to the function that provides the
- *                 clipboard data
- * \param cleanup A function pointer to the function that cleans up the
- *                clipboard data
- * \param userdata An opaque pointer that will be forwarded to the callbacks
- * \param mime_types A list of mime-types that are being offered
- * \param num_mime_types The number of mime-types in the mime_types list
+ * \param callback a function pointer to the function that provides the
+ *                 clipboard data.
+ * \param cleanup a function pointer to the function that cleans up the
+ *                clipboard data.
+ * \param userdata an opaque pointer that will be forwarded to the callbacks.
+ * \param mime_types a list of mime-types that are being offered.
+ * \param num_mime_types the number of mime-types in the mime_types list.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -217,8 +217,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
  * The size of text data does not include the terminator, but the text is
  * guaranteed to be null terminated.
  *
- * \param mime_type The mime type to read from the clipboard
- * \param size A pointer filled in with the length of the returned data
+ * \param mime_type the mime type to read from the clipboard.
+ * \param size a pointer filled in with the length of the returned data.
  * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
  *          for more information. Caller must call SDL_free() on the returned
  *          pointer when done with it.
@@ -233,7 +233,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetClipboardData(const char *mime_type, si
 /**
  * Query whether there is data in the clipboard for the provided mime type.
  *
- * \param mime_type The mime type to check for data for
+ * \param mime_type the mime type to check for data for.
  * \returns SDL_TRUE if there exists data in clipboard for the provided mime
  *          type, SDL_FALSE if it does not.
  *

include/SDL3/SDL_dialog.h

@@ -82,9 +82,9 @@ typedef struct SDL_DialogFileFilter
  * no filter was selected or if the platform or method doesn't support
  * fetching the selected filter.
  *
- * \param userdata An app-provided pointer, for the callback's use.
- * \param filelist The file(s) chosen by the user.
- * \param filter Index of the selected filter.
+ * \param userdata an app-provided pointer, for the callback's use.
+ * \param filelist the file(s) chosen by the user.
+ * \param filter index of the selected filter.
  *
  * \since This datatype is available since SDL 3.0.0.
  *
@@ -117,7 +117,7 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
  * requires an event-handling loop. Apps that do not use SDL to handle events
  * should add a call to SDL_PumpEvents in their main loop.
  *
- * \param callback An SDL_DialogFileCallback to be invoked when the user
+ * \param callback an SDL_DialogFileCallback to be invoked when the user
  *                 selects a file and accepts, or cancels the dialog, or an
  *                 error occurs. The first argument is a null-terminated list
  *                 of C strings, representing the paths chosen by the user.
@@ -130,17 +130,17 @@ typedef void(SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const
  *                 index of the terminating NULL filter) if no filter was
  *                 chosen, or -1 if the platform does not support detecting
  *                 the selected filter.
- * \param userdata An optional pointer to pass extra data to the callback when
+ * \param userdata an optional pointer to pass extra data to the callback when
  *                 it will be invoked.
- * \param window The window that the dialog should be modal for. May be NULL.
+ * \param window the window that the dialog should be modal for. May be NULL.
  *               Not all platforms support this option.
- * \param filters A list of SDL_DialogFileFilter's. May be NULL. Not all
+ * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
  *                platforms support this option, and platforms that do support
  *                it may allow the user to ignore the filters.
- * \param nfilters The number of filters. Ignored if filters is NULL.
- * \param default_location The default folder or file to start the dialog at.
+ * \param nfilters the number of filters. Ignored if filters is NULL.
+ * \param default_location the default folder or file to start the dialog at.
  *                         May be NULL. Not all platforms support this option.
- * \param allow_many If non-zero, the user will be allowed to select multiple
+ * \param allow_many if non-zero, the user will be allowed to select multiple
  *                   entries. Not all platforms support this option.
  *
  * \since This function is available since SDL 3.0.0.
@@ -174,7 +174,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c
  * requires an event-handling loop. Apps that do not use SDL to handle events
  * should add a call to SDL_PumpEvents in their main loop.
  *
- * \param callback An SDL_DialogFileCallback to be invoked when the user
+ * \param callback an SDL_DialogFileCallback to be invoked when the user
  *                 selects a file and accepts, or cancels the dialog, or an
  *                 error occurs. The first argument is a null-terminated list
  *                 of C strings, representing the paths chosen by the user.
@@ -187,15 +187,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c
  *                 index of the terminating NULL filter) if no filter was
  *                 chosen, or -1 if the platform does not support detecting
  *                 the selected filter.
- * \param userdata An optional pointer to pass extra data to the callback when
+ * \param userdata an optional pointer to pass extra data to the callback when
  *                 it will be invoked.
- * \param window The window that the dialog should be modal for. May be NULL.
+ * \param window the window that the dialog should be modal for. May be NULL.
  *               Not all platforms support this option.
- * \param filters A list of SDL_DialogFileFilter's. May be NULL. Not all
+ * \param filters a list of SDL_DialogFileFilter's. May be NULL. Not all
  *                platforms support this option, and platforms that do support
  *                it may allow the user to ignore the filters.
- * \param nfilters The number of filters. Ignored if filters is NULL.
- * \param default_location The default folder or file to start the dialog at.
+ * \param nfilters the number of filters. Ignored if filters is NULL.
+ * \param default_location the default folder or file to start the dialog at.
  *                         May be NULL. Not all platforms support this option.
  *
  * \since This function is available since SDL 3.0.0.
@@ -229,7 +229,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c
  * requires an event-handling loop. Apps that do not use SDL to handle events
  * should add a call to SDL_PumpEvents in their main loop.
  *
- * \param callback An SDL_DialogFileCallback to be invoked when the user
+ * \param callback an SDL_DialogFileCallback to be invoked when the user
  *                 selects a file and accepts, or cancels the dialog, or an
  *                 error occurs. The first argument is a null-terminated list
  *                 of C strings, representing the paths chosen by the user.
@@ -238,13 +238,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c
  *                 it can be fetched with SDL_GetError(). The second argument
  *                 is the userdata pointer passed to the function. The third
  *                 argument is always -1 for SDL_ShowOpenFolderDialog.
- * \param userdata An optional pointer to pass extra data to the callback when
+ * \param userdata an optional pointer to pass extra data to the callback when
  *                 it will be invoked.
- * \param window The window that the dialog should be modal for. May be NULL.
+ * \param window the window that the dialog should be modal for. May be NULL.
  *               Not all platforms support this option.
- * \param default_location The default folder or file to start the dialog at.
+ * \param default_location the default folder or file to start the dialog at.
  *                         May be NULL. Not all platforms support this option.
- * \param allow_many If non-zero, the user will be allowed to select multiple
+ * \param allow_many if non-zero, the user will be allowed to select multiple
  *                   entries. Not all platforms support this option.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_error.h

@@ -53,9 +53,9 @@ extern "C" {
  * }
  * ```
  *
- * \param fmt a printf()-style message format string
+ * \param fmt a printf()-style message format string.
  * \param ... additional parameters matching % tokens in the `fmt` string, if
- *            any
+ *            any.
  * \returns always -1.
  *
  * \since This function is available since SDL 3.0.0.
@@ -70,7 +70,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char
  *
  * This function does not do any memory allocation.
  *
- * \returns -1
+ * \returns -1.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -115,7 +115,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetError(void);
 /**
  * Clear any previous error message for this thread.
  *
- * \returns 0
+ * \returns 0.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_events.h

@@ -958,7 +958,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
  * If you need to check for a range of event types, use SDL_HasEvents()
  * instead.
  *
- * \param type the type of event to be queried; see SDL_EventType for details
+ * \param type the type of event to be queried; see SDL_EventType for details.
  * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
  *          events matching `type` are not present.
  *
@@ -975,9 +975,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
  * If you need to check for a single event type, use SDL_HasEvent() instead.
  *
  * \param minType the low end of event type to be queried, inclusive; see
- *                SDL_EventType for details
+ *                SDL_EventType for details.
  * \param maxType the high end of event type to be queried, inclusive; see
- *                SDL_EventType for details
+ *                SDL_EventType for details.
  * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
  *          present, or SDL_FALSE if not.
  *
@@ -1005,7 +1005,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp
  * use SDL_PeepEvents() to remove and clean up those events before calling
  * this function.
  *
- * \param type the type of event to be cleared; see SDL_EventType for details
+ * \param type the type of event to be cleared; see SDL_EventType for details.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1028,9 +1028,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
  * on the main thread immediately before the flush call.
  *
  * \param minType the low end of event type to be cleared, inclusive; see
- *                SDL_EventType for details
+ *                SDL_EventType for details.
  * \param maxType the high end of event type to be cleared, inclusive; see
- *                SDL_EventType for details
+ *                SDL_EventType for details.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1071,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
  * ```
  *
  * \param event the SDL_Event structure to be filled with the next event from
- *              the queue, or NULL
+ *              the queue, or NULL.
  * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none
  *          available.
  *
@@ -1093,7 +1093,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event);
  * this function in the thread that initialized the video subsystem.
  *
  * \param event the SDL_Event structure to be filled in with the next event
- *              from the queue, or NULL
+ *              from the queue, or NULL.
  * \returns SDL_TRUE on success or SDL_FALSE if there was an error while
  *          waiting for events; call SDL_GetError() for more information.
  *
@@ -1119,9 +1119,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event);
  * system scheduling.
  *
  * \param event the SDL_Event structure to be filled in with the next event
- *              from the queue, or NULL
+ *              from the queue, or NULL.
  * \param timeoutMS the maximum number of milliseconds to wait for the next
- *                  available event
+ *                  available event.
  * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed
  *          without any events available.
  *
@@ -1154,7 +1154,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint
  * get an event type that does not conflict with other code that also wants
  * its own custom event types.
  *
- * \param event the SDL_Event to be added to the queue
+ * \param event the SDL_Event to be added to the queue.
  * \returns 1 on success, 0 if the event was filtered, or a negative error
  *          code on failure; call SDL_GetError() for more information. A
  *          common reason for error is the event queue being full.
@@ -1171,8 +1171,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
  * A function pointer used for callbacks that watch the event queue.
  *
  * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
- *                 SDL_AddEventWatch, etc
- * \param event the event that triggered the callback
+ *                 SDL_AddEventWatch, etc.
+ * \param event the event that triggered the callback.
  * \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.
  *
@@ -1218,8 +1218,8 @@ typedef int (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
  * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
  * not.
  *
- * \param filter An SDL_EventFilter function to call when an event happens
- * \param userdata a pointer that is passed to `filter`
+ * \param filter an SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`.
  *
  * \threadsafety SDL may call the filter callback at any time from any thread;
  *               the application is responsible for locking resources the
@@ -1241,9 +1241,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void
  * This function can be used to "chain" filters, by saving the existing filter
  * before replacing it with a function that will call that saved filter.
  *
- * \param filter the current callback function will be stored here
+ * \param filter the current callback function will be stored here.
  * \param userdata the pointer that is passed to the current event filter will
- *                 be stored here
+ *                 be stored here.
  * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1271,7 +1271,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
  * through SDL_PeepEvents().
  *
  * \param filter an SDL_EventFilter function to call when an event happens.
- * \param userdata a pointer that is passed to `filter`
+ * \param userdata a pointer that is passed to `filter`.
  * \returns 0 on success, or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1290,8 +1290,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *
  * This function takes the same input as SDL_AddEventWatch() to identify and
  * delete the corresponding callback.
  *
- * \param filter the function originally passed to SDL_AddEventWatch()
- * \param userdata the pointer originally passed to SDL_AddEventWatch()
+ * \param filter the function originally passed to SDL_AddEventWatch().
+ * \param userdata the pointer originally passed to SDL_AddEventWatch().
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1307,8 +1307,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, void
  * this function does not change the filter permanently, it only uses the
  * supplied filter until this function returns.
  *
- * \param filter the SDL_EventFilter function to call when an event happens
- * \param userdata a pointer that is passed to `filter`
+ * \param filter the SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1320,8 +1320,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *
 /**
  * Set the state of processing events by type.
  *
- * \param type the type of event; see SDL_EventType for details
- * \param enabled whether to process the event or not
+ * \param type the type of event; see SDL_EventType for details.
+ * \param enabled whether to process the event or not.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1332,7 +1332,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabl
 /**
  * Query the state of processing events by type.
  *
- * \param type the type of event; see SDL_EventType for details
+ * \param type the type of event; see SDL_EventType for details.
  * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1345,7 +1345,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type);
  * Allocate a set of user-defined events, and return the beginning event
  * number for that set of events.
  *
- * \param numevents the number of events to be allocated
+ * \param numevents the number of events to be allocated.
  * \returns the beginning event number, or 0 if numevents is invalid or if
  *          there are not enough user-defined events left.
  *
@@ -1361,7 +1361,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
  * You can use this to allocate memory for user events that will be
  * automatically freed after the event is processed.
  *
- * \param size the amount of memory to allocate
+ * \param size the amount of memory to allocate.
  * \returns a pointer to the memory allocated or NULL on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_filesystem.h

@@ -127,8 +127,8 @@ extern SDL_DECLSPEC char *SDLCALL SDL_GetBasePath(void);
  * The pointer returned is owned by the caller. Please call SDL_free() on the
  * pointer when done with it.
  *
- * \param org the name of your organization
- * \param app the name of your application
+ * \param org the name of your organization.
+ * \param app the name of your application.
  * \returns a UTF-8 string of the user directory in platform-dependent
  *          notation. NULL if there's a problem (creating directory failed,
  *          etc.).
@@ -232,7 +232,7 @@ typedef enum SDL_Folder
  *
  * If NULL is returned, the error may be obtained with SDL_GetError().
  *
- * \param folder The type of folder to find
+ * \param folder the type of folder to find.
  * \returns either a null-terminated C string containing the full path to the
  *          folder, or NULL if an error happened.
  *
@@ -277,7 +277,7 @@ typedef Uint32 SDL_GlobFlags;
 /**
  * Create a directory.
  *
- * \param path the path of the directory to create
+ * \param path the path of the directory to create.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -298,9 +298,9 @@ typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char
  * callback, called once for each directory entry, until all results have been
  * provided or the callback returns <= 0.
  *
- * \param path the path of the directory to enumerate
- * \param callback a function that is called for each entry in the directory
- * \param userdata a pointer that is passed to `callback`
+ * \param path the path of the directory to enumerate.
+ * \param callback a function that is called for each entry in the directory.
+ * \param userdata a pointer that is passed to `callback`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -311,7 +311,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateDirectory(const char *path, SDL_Enu
 /**
  * Remove a file or an empty directory.
  *
- * \param path the path of the directory to enumerate
+ * \param path the path of the directory to enumerate.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -322,8 +322,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemovePath(const char *path);
 /**
  * Rename a file or directory.
  *
- * \param oldpath the old path
- * \param newpath the new path
+ * \param oldpath the old path.
+ * \param newpath the new path.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -334,9 +334,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenamePath(const char *oldpath, const char *
 /**
  * Get information about a filesystem path.
  *
- * \param path the path to query
+ * \param path the path to query.
  * \param info a pointer filled in with information about the path, or NULL to
- *             check for the existence of a file
+ *             check for the existence of a file.
  * \returns 0 on success or a negative error code if the file doesn't exist,
  *          or another failure; call SDL_GetError() for more information.
  *
@@ -363,7 +363,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
  *
  * You must free the returned pointer with SDL_free() when done with it.
  *
- * \param path the path of the directory to enumerate
+ * \param path the path of the directory to enumerate.
  * \param pattern the pattern that files in the directory must match. Can be
  *                NULL.
  * \param flags `SDL_GLOB_*` bitflags that affect this search.

include/SDL3/SDL_gamepad.h

@@ -299,7 +299,7 @@ typedef struct SDL_GamepadBinding
  * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
  * ```
  *
- * \param mapping the mapping string
+ * \param mapping the mapping string.
  * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
  *          -1 on error; call SDL_GetError() for more information.
  *
@@ -329,9 +329,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
  * processing it, so take this into consideration if you are in a memory
  * constrained environment.
  *
- * \param src the data stream for the mappings to be added
+ * \param src the data stream for the mappings to be added.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
- *                even in the case of an error
+ *                even in the case of an error.
  * \returns the number of mappings added or -1 on error; call SDL_GetError()
  *          for more information.
  *
@@ -359,7 +359,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
  * specified will be ignored (i.e. mappings for Linux will be ignored in
  * Windows, etc).
  *
- * \param file the mappings file to load
+ * \param file the mappings file to load.
  * \returns the number of mappings added or -1 on error; call SDL_GetError()
  *          for more information.
  *
@@ -406,7 +406,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
  *
  * The returned string must be freed with SDL_free().
  *
- * \param guid a structure containing the GUID for which a mapping is desired
+ * \param guid a structure containing the GUID for which a mapping is desired.
  * \returns a mapping string or NULL on error; call SDL_GetError() for more
  *          information.
  *
@@ -424,7 +424,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID
  *
  * Details about mappings are discussed with SDL_AddGamepadMapping().
  *
- * \param gamepad the gamepad you want to get the current mapping for
+ * \param gamepad the gamepad you want to get the current mapping for.
  * \returns a string that has the gamepad's mapping or NULL if no mapping is
  *          available; call SDL_GetError() for more information.
  *
@@ -442,9 +442,9 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
  *
  * Details about mappings are discussed with SDL_AddGamepadMapping().
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \param mapping the mapping to use for this device, or NULL to clear the
- *                mapping
+ *                mapping.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -469,7 +469,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
 /**
  * Get a list of currently connected gamepads.
  *
- * \param count a pointer filled in with the number of gamepads returned
+ * \param count a pointer filled in with the number of gamepads returned.
  * \returns a 0 terminated array of joystick instance IDs which should be
  *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
  *          more details.
@@ -484,7 +484,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetGamepads(int *count);
 /**
  * Check if the given joystick is supported by the gamepad interface.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns SDL_TRUE if the given joystick is supported by the gamepad
  *          interface, SDL_FALSE if it isn't or it's an invalid index.
  *
@@ -502,7 +502,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the name of the selected gamepad. If no name can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -520,7 +520,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickI
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the path of the selected gamepad. If no path can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -536,8 +536,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickI
  *
  * This can be called before any gamepads are opened.
  *
- * \param instance_id the joystick instance ID
- * \returns the player index of a gamepad, or -1 if it's not available
+ * \param instance_id the joystick instance ID.
+ * \returns the player index of a gamepad, or -1 if it's not available.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -551,9 +551,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadInstancePlayerIndex(SDL_JoystickID
  *
  * This can be called before any gamepads are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the GUID of the selected gamepad. If called on an invalid index,
- *          this function returns a zero GUID
+ *          this function returns a zero GUID.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -569,9 +569,9 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joys
  * This can be called before any gamepads are opened. If the vendor ID isn't
  * available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the USB vendor ID of the selected gamepad. If called on an invalid
- *          index, this function returns zero
+ *          index, this function returns zero.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -586,9 +586,9 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceVendor(SDL_JoystickID i
  * This can be called before any gamepads are opened. If the product ID isn't
  * available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the USB product ID of the selected gamepad. If called on an
- *          invalid index, this function returns zero
+ *          invalid index, this function returns zero.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -603,9 +603,9 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProduct(SDL_JoystickID
  * This can be called before any gamepads are opened. If the product version
  * isn't available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the product version of the selected gamepad. If called on an
- *          invalid index, this function returns zero
+ *          invalid index, this function returns zero.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -619,7 +619,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadInstanceProductVersion(SDL_Joys
  *
  * This can be called before any gamepads are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the gamepad type.
  *
  * \since This function is available since SDL 3.0.0.
@@ -635,7 +635,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadInstanceType(SDL_Joyst
  *
  * This can be called before any gamepads are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the gamepad type.
  *
  * \since This function is available since SDL 3.0.0.
@@ -651,7 +651,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadInstanceType(SDL_J
  *
  * This can be called before any gamepads are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
  *          no mapping is available.
  *
@@ -665,7 +665,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID i
 /**
  * Open a gamepad for use.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns a gamepad identifier or NULL if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -680,7 +680,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance
  * Get the SDL_Gamepad associated with a joystick instance ID, if it has been
  * opened.
  *
- * \param instance_id the joystick instance ID of the gamepad
+ * \param instance_id the joystick instance ID of the gamepad.
  * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
  *          opened yet; call SDL_GetError() for more information.
  *
@@ -691,7 +691,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_Joysti
 /**
  * Get the SDL_Gamepad associated with a player index.
  *
- * \param player_index the player index, which different from the instance ID
+ * \param player_index the player index, which different from the instance ID.
  * \returns the SDL_Gamepad associated with a player index.
  *
  * \since This function is available since SDL 3.0.0.
@@ -720,7 +720,7 @@ extern SDL_DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int playe
  *   simple trigger rumble
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -741,7 +741,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa
  * Get the instance ID of an opened gamepad.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  * \returns the instance ID of the specified gamepad on success or 0 on
  *          failure; call SDL_GetError() for more information.
  *
@@ -755,7 +755,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadInstanceID(SDL_Gamepad
  * The returned string follows the SDL_GetStringRule.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  * \returns the implementation dependent name for the gamepad, or NULL if
  *          there is no name or the identifier passed is invalid.
  *
@@ -771,7 +771,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad)
  * The returned string follows the SDL_GetStringRule.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  * \returns the implementation dependent path for the gamepad, or NULL if
  *          there is no path or the identifier passed is invalid.
  *
@@ -825,7 +825,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
  * Set the player index of an opened gamepad.
  *
  * \param gamepad the gamepad object to adjust.
- * \param player_index Player index to assign to this gamepad, or -1 to clear
+ * \param player_index player index to assign to this gamepad, or -1 to clear
  *                     the player index and turn off player LEDs.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
@@ -953,7 +953,7 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *
  * Check if a gamepad has been opened and is currently connected.
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  * \returns SDL_TRUE if the gamepad has been opened and is currently
  *          connected, or SDL_FALSE if not.
  *
@@ -973,7 +973,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
  * SDL_CloseJoystick() on it, for example, since doing so will likely cause
  * SDL to crash.
  *
- * \param gamepad the gamepad object that you want to get a joystick from
+ * \param gamepad the gamepad object that you want to get a joystick from.
  * \returns an SDL_Joystick object; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
@@ -986,7 +986,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *ga
  * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
  * and check the state of the gamepad when you want gamepad information.
  *
- * \param enabled whether to process gamepad events or not
+ * \param enabled whether to process gamepad events or not.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1013,8 +1013,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
 /**
  * Get the SDL joystick layer bindings for a gamepad.
  *
- * \param gamepad a gamepad
- * \param count a pointer filled in with the number of bindings returned
+ * \param gamepad a gamepad.
+ * \param count a pointer filled in with the number of bindings returned.
  * \returns a NULL terminated array of pointers to bindings which should be
  *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
  *          more details.
@@ -1042,7 +1042,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
  * You do not normally need to call this function unless you are parsing
  * SDL_Gamepad mappings in your own code.
  *
- * \param str string representing a SDL_GamepadType type
+ * \param str string representing a SDL_GamepadType type.
  * \returns the SDL_GamepadType enum corresponding to the input string, or
  *          `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found.
  *
@@ -1057,7 +1057,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param type an enum value for a given SDL_GamepadType
+ * \param type an enum value for a given SDL_GamepadType.
  * \returns a string for the given type, or NULL if an invalid type is
  *          specified. The string returned is of the format used by
  *          SDL_Gamepad mapping strings.
@@ -1080,7 +1080,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadStringForType(SDL_GamepadT
  * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
  * respectively.
  *
- * \param str string representing a SDL_Gamepad axis
+ * \param str string representing a SDL_Gamepad axis.
  * \returns the SDL_GamepadAxis enum corresponding to the input string, or
  *          `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
  *
@@ -1095,7 +1095,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param axis an enum value for a given SDL_GamepadAxis
+ * \param axis an enum value for a given SDL_GamepadAxis.
  * \returns a string for the given axis, or NULL if an invalid axis is
  *          specified. The string returned is of the format used by
  *          SDL_Gamepad mapping strings.
@@ -1112,8 +1112,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad
  * This merely reports whether the gamepad's mapping defined this axis, as
  * that is all the information SDL has about the physical device.
  *
- * \param gamepad a gamepad
- * \param axis an axis enum value (an SDL_GamepadAxis value)
+ * \param gamepad a gamepad.
+ * \param axis an axis enum value (an SDL_GamepadAxis value).
  * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1135,8 +1135,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD
  * return a negative value. Note that this differs from the value reported by
  * the lower-level SDL_GetJoystickAxis(), which normally uses the full range.
  *
- * \param gamepad a gamepad
- * \param axis an axis index (one of the SDL_GamepadAxis values)
+ * \param gamepad a gamepad.
+ * \param axis an axis index (one of the SDL_GamepadAxis values).
  * \returns axis state (including 0) on success or 0 (also) on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1155,7 +1155,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_
  * You do not normally need to call this function unless you are parsing
  * SDL_Gamepad mappings in your own code.
  *
- * \param str string representing a SDL_Gamepad axis
+ * \param str string representing a SDL_Gamepad axis.
  * \returns the SDL_GamepadButton enum corresponding to the input string, or
  *          `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
  *
@@ -1170,7 +1170,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param button an enum value for a given SDL_GamepadButton
+ * \param button an enum value for a given SDL_GamepadButton.
  * \returns a string for the given button, or NULL if an invalid button is
  *          specified. The string returned is of the format used by
  *          SDL_Gamepad mapping strings.
@@ -1187,8 +1187,8 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetGamepadStringForButton(SDL_Gamepa
  * This merely reports whether the gamepad's mapping defined this button, as
  * that is all the information SDL has about the physical device.
  *
- * \param gamepad a gamepad
- * \param button a button enum value (an SDL_GamepadButton value)
+ * \param gamepad a gamepad.
+ * \param button a button enum value (an SDL_GamepadButton value).
  * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1200,8 +1200,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad,
 /**
  * Get the current state of a button on a gamepad.
  *
- * \param gamepad a gamepad
- * \param button a button index (one of the SDL_GamepadButton values)
+ * \param gamepad a gamepad.
+ * \param button a button index (one of the SDL_GamepadButton values).
  * \returns 1 for pressed state or 0 for not pressed state or error; call
  *          SDL_GetError() for more information.
  *
@@ -1215,9 +1215,9 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL
 /**
  * Get the label of a button on a gamepad.
  *
- * \param type the type of gamepad to check
- * \param button a button index (one of the SDL_GamepadButton values)
- * \returns the SDL_GamepadButtonLabel enum corresponding to the button label
+ * \param type the type of gamepad to check.
+ * \param button a button index (one of the SDL_GamepadButton values).
+ * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1228,9 +1228,9 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT
 /**
  * Get the label of a button on a gamepad.
  *
- * \param gamepad a gamepad
- * \param button a button index (one of the SDL_GamepadButton values)
- * \returns the SDL_GamepadButtonLabel enum corresponding to the button label
+ * \param gamepad a gamepad.
+ * \param button a button index (one of the SDL_GamepadButton values).
+ * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1241,8 +1241,8 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL
 /**
  * Get the number of touchpads on a gamepad.
  *
- * \param gamepad a gamepad
- * \returns number of touchpads
+ * \param gamepad a gamepad.
+ * \returns number of touchpads.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1254,9 +1254,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad)
  * Get the number of supported simultaneous fingers on a touchpad on a game
  * gamepad.
  *
- * \param gamepad a gamepad
- * \param touchpad a touchpad
- * \returns number of supported simultaneous fingers
+ * \param gamepad a gamepad.
+ * \param touchpad a touchpad.
+ * \returns number of supported simultaneous fingers.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1268,15 +1268,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga
 /**
  * Get the current state of a finger on a touchpad on a gamepad.
  *
- * \param gamepad a gamepad
- * \param touchpad a touchpad
- * \param finger a finger
- * \param state filled with state
+ * \param gamepad a gamepad.
+ * \param touchpad a touchpad.
+ * \param finger a finger.
+ * \param state filled with state.
  * \param x filled with x position, normalized 0 to 1, with the origin in the
- *          upper left
+ *          upper left.
  * \param y filled with y position, normalized 0 to 1, with the origin in the
- *          upper left
- * \param pressure filled with pressure value
+ *          upper left.
+ * \param pressure filled with pressure value.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1289,8 +1289,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepa
 /**
  * Return whether a gamepad has a particular sensor.
  *
- * \param gamepad The gamepad to query
- * \param type The type of sensor to query
+ * \param gamepad the gamepad to query.
+ * \param type the type of sensor to query.
  * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1304,9 +1304,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad,
 /**
  * Set whether data reporting for a gamepad sensor is enabled.
  *
- * \param gamepad The gamepad to update
- * \param type The type of sensor to enable/disable
- * \param enabled Whether data reporting should be enabled
+ * \param gamepad the gamepad to update.
+ * \param type the type of sensor to enable/disable.
+ * \param enabled whether data reporting should be enabled.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1320,8 +1320,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad
 /**
  * Query whether sensor data reporting is enabled for a gamepad.
  *
- * \param gamepad The gamepad to query
- * \param type The type of sensor to query
+ * \param gamepad the gamepad to query.
+ * \param type the type of sensor to query.
  * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1333,8 +1333,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep
 /**
  * Get the data rate (number of events per second) of a gamepad sensor.
  *
- * \param gamepad The gamepad to query
- * \param type The type of sensor to query
+ * \param gamepad the gamepad to query.
+ * \param type the type of sensor to query.
  * \returns the data rate, or 0.0f if the data rate is not available.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1347,10 +1347,10 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game
  * The number of values and interpretation of the data is sensor dependent.
  * See SDL_sensor.h for the details for each type of sensor.
  *
- * \param gamepad The gamepad to query
- * \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
+ * \param gamepad the gamepad to query.
+ * \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.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1367,13 +1367,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, S
  * This function requires you to process SDL events or call
  * SDL_UpdateJoysticks() to update rumble state.
  *
- * \param gamepad The gamepad to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left)
- *                             rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right)
- *                              rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if rumble isn't supported on this gamepad
+ * \param gamepad the gamepad to vibrate.
+ * \param low_frequency_rumble the intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF.
+ * \param high_frequency_rumble the intensity of the high frequency (right)
+ *                              rumble motor, from 0 to 0xFFFF.
+ * \param duration_ms the duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if rumble isn't supported on this gamepad.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1392,12 +1392,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 l
  * This function requires you to process SDL events or call
  * SDL_UpdateJoysticks() to update rumble state.
  *
- * \param gamepad The gamepad to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0
- *                    to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0
- *                     to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \param gamepad the gamepad to vibrate.
+ * \param left_rumble the intensity of the left trigger rumble motor, from 0
+ *                    to 0xFFFF.
+ * \param right_rumble the intensity of the right trigger rumble motor, from 0
+ *                     to 0xFFFF.
+ * \param duration_ms the duration of the rumble effect, in milliseconds.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1416,10 +1416,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad,
  * For gamepads with a single color LED, the maximum of the RGB values will be
  * used as the LED brightness.
  *
- * \param gamepad The gamepad to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
+ * \param gamepad the gamepad to update.
+ * \param red the intensity of the red LED.
+ * \param green the intensity of the green LED.
+ * \param blue the intensity of the blue LED.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1430,9 +1430,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 re
 /**
  * Send a gamepad specific effect packet.
  *
- * \param gamepad The gamepad to affect
- * \param data The data to send to the gamepad
- * \param size The size of the data to send to the gamepad
+ * \param gamepad the gamepad to affect.
+ * \param data the data to send to the gamepad.
+ * \param size the size of the data to send to the gamepad.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1444,7 +1444,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, cons
  * Close a gamepad previously opened with SDL_OpenGamepad().
  *
  * \param gamepad a gamepad identifier previously returned by
- *                SDL_OpenGamepad()
+ *                SDL_OpenGamepad().
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1458,9 +1458,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param gamepad the gamepad to query
- * \param button a button on the gamepad
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamepad the gamepad to query.
+ * \param button a button on the gamepad.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1473,9 +1473,9 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButto
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param gamepad the gamepad to query
- * \param axis an axis on the gamepad
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamepad the gamepad to query.
+ * \param axis an axis on the gamepad.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_guid.h

@@ -68,9 +68,9 @@ typedef struct SDL_GUID {
  *
  * You should supply at least 33 bytes for pszGUID.
  *
- * \param guid the SDL_GUID you wish to convert to string
- * \param pszGUID buffer in which to write the ASCII string
- * \param cbGUID the size of pszGUID
+ * \param guid the SDL_GUID you wish to convert to string.
+ * \param pszGUID buffer in which to write the ASCII string.
+ * \param cbGUID the size of pszGUID.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -87,7 +87,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, i
  * an invalid GUID, the function will silently succeed, but the GUID generated
  * will not be useful.
  *
- * \param pchGUID string containing an ASCII representation of a GUID
+ * \param pchGUID string containing an ASCII representation of a GUID.
  * \returns a SDL_GUID structure.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_haptic.h

@@ -932,7 +932,8 @@ typedef Uint32 SDL_HapticID;
 /**
  * Get a list of currently connected haptic devices.
  *
- * \param count a pointer filled in with the number of haptic devices returned
+ * \param count a pointer filled in with the number of haptic devices
+ *              returned.
  * \returns a 0 terminated array of haptic device instance IDs which should be
  *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
  *          more details.
@@ -950,7 +951,7 @@ extern SDL_DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the haptic device instance ID
+ * \param instance_id the haptic device instance ID.
  * \returns the name of the selected haptic device. If no name can be found,
  *          this function returns NULL; call SDL_GetError() for more
  *          information.
@@ -972,7 +973,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHapticInstanceName(SDL_HapticID i
  * autocenter will be disabled. To modify these values use SDL_SetHapticGain()
  * and SDL_SetHapticAutocenter().
  *
- * \param instance_id the haptic device instance ID
+ * \param instance_id the haptic device instance ID.
  * \returns the device identifier or NULL on failure; call SDL_GetError() for
  *          more information.
  *
@@ -991,7 +992,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id)
 /**
  * Get the SDL_Haptic associated with an instance ID, if it has been opened.
  *
- * \param instance_id the instance ID to get the SDL_Haptic for
+ * \param instance_id the instance ID to get the SDL_Haptic for.
  * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been
  *          opened yet; call SDL_GetError() for more information.
  *
@@ -1002,7 +1003,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_GetHapticFromInstanceID(SDL_HapticID
 /**
  * Get the instance ID of an opened haptic device.
  *
- * \param haptic the SDL_Haptic device to query
+ * \param haptic the SDL_Haptic device to query.
  * \returns the instance ID of the specified haptic device on success or 0 on
  *          failure; call SDL_GetError() for more information.
  *
@@ -1015,7 +1016,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticInstanceID(SDL_Haptic *hap
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick()
+ * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
  * \returns the name of the selected haptic device. If no name can be found,
  *          this function returns NULL; call SDL_GetError() for more
  *          information.
@@ -1053,7 +1054,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromMouse(void);
 /**
  * Query if a joystick has haptic features.
  *
- * \param joystick the SDL_Joystick to test for haptic capabilities
+ * \param joystick the SDL_Joystick to test for haptic capabilities.
  * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1073,7 +1074,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick
  * device will also get unallocated and you'll be unable to use force feedback
  * on that device.
  *
- * \param joystick the SDL_Joystick to create a haptic device from
+ * \param joystick the SDL_Joystick to create a haptic device from.
  * \returns a valid haptic device identifier on success or NULL on failure;
  *          call SDL_GetError() for more information.
  *
@@ -1087,7 +1088,7 @@ extern SDL_DECLSPEC SDL_Haptic *SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick
 /**
  * Close a haptic device previously opened with SDL_OpenHaptic().
  *
- * \param haptic the SDL_Haptic device to close
+ * \param haptic the SDL_Haptic device to close.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1102,7 +1103,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic);
  * approximation. Always check to see if your created effect was actually
  * created and do not rely solely on SDL_GetMaxHapticEffects().
  *
- * \param haptic the SDL_Haptic device to query
+ * \param haptic the SDL_Haptic device to query.
  * \returns the number of effects the haptic device can store or a negative
  *          error code on failure; call SDL_GetError() for more information.
  *
@@ -1118,7 +1119,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic);
  *
  * This is not supported on all platforms, but will always return a value.
  *
- * \param haptic the SDL_Haptic device to query maximum playing effects
+ * \param haptic the SDL_Haptic device to query maximum playing effects.
  * \returns the number of effects the haptic device can play at the same time
  *          or a negative error code on failure; call SDL_GetError() for more
  *          information.
@@ -1133,7 +1134,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti
 /**
  * Get the haptic device's supported features in bitwise manner.
  *
- * \param haptic the SDL_Haptic device to query
+ * \param haptic the SDL_Haptic device to query.
  * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
  *          on failure; call SDL_GetError() for more information.
  *
@@ -1150,7 +1151,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic);
  * The number of haptic axes might be useful if working with the
  * SDL_HapticDirection effect.
  *
- * \param haptic the SDL_Haptic device to query
+ * \param haptic the SDL_Haptic device to query.
  * \returns the number of axes on success or a negative error code on failure;
  *          call SDL_GetError() for more information.
  *
@@ -1161,8 +1162,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic);
 /**
  * Check to see if an effect is supported by a haptic device.
  *
- * \param haptic the SDL_Haptic device to query
- * \param effect the desired effect to query
+ * \param haptic the SDL_Haptic device to query.
+ * \param effect the desired effect to query.
  * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1175,9 +1176,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti
 /**
  * Create a new haptic effect on a specified device.
  *
- * \param haptic an SDL_Haptic device to create the effect on
+ * \param haptic an SDL_Haptic device to create the effect on.
  * \param effect an SDL_HapticEffect structure containing the properties of
- *               the effect to create
+ *               the effect to create.
  * \returns the ID of the effect on success or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *
@@ -1197,10 +1198,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const
  * start playing from the start. You also cannot change the type either when
  * running SDL_UpdateHapticEffect().
  *
- * \param haptic the SDL_Haptic device that has the effect
- * \param effect the identifier of the effect to update
+ * \param haptic the SDL_Haptic device that has the effect.
+ * \param effect the identifier of the effect to update.
  * \param data an SDL_HapticEffect structure containing the new effect
- *             properties to use
+ *             properties to use.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1220,10 +1221,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int e
  * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
  * instead.
  *
- * \param haptic the SDL_Haptic device to run the effect on
- * \param effect the ID of the haptic effect to run
+ * \param haptic the SDL_Haptic device to run the effect on.
+ * \param effect the ID of the haptic effect to run.
  * \param iterations the number of iterations to run the effect; use
- *                   `SDL_HAPTIC_INFINITY` to repeat forever
+ *                   `SDL_HAPTIC_INFINITY` to repeat forever.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1238,8 +1239,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effe
 /**
  * Stop the haptic effect on its associated haptic device.
  *
- * \param haptic the SDL_Haptic device to stop the effect on
- * \param effect the ID of the haptic effect to stop
+ * \param haptic the SDL_Haptic device to stop the effect on.
+ * \param effect the ID of the haptic effect to stop.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1256,8 +1257,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int eff
  * This will stop the effect if it's running. Effects are automatically
  * destroyed when the device is closed.
  *
- * \param haptic the SDL_Haptic device to destroy the effect on
- * \param effect the ID of the haptic effect to destroy
+ * \param haptic the SDL_Haptic device to destroy the effect on.
+ * \param effect the ID of the haptic effect to destroy.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1270,8 +1271,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int
  *
  * Device must support the SDL_HAPTIC_STATUS feature.
  *
- * \param haptic the SDL_Haptic device to query for the effect status on
- * \param effect the ID of the haptic effect to query its status
+ * \param haptic the SDL_Haptic device to query for the effect status on.
+ * \param effect the ID of the haptic effect to query its status.
  * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
  *          code on failure; call SDL_GetError() for more information.
  *
@@ -1289,8 +1290,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, in
  * SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
  * maximum.
  *
- * \param haptic the SDL_Haptic device to set the gain on
- * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
+ * \param haptic the SDL_Haptic device to set the gain on.
+ * \param gain value to set the gain to, should be between 0 and 100 (0 -
+ *             100).
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1308,8 +1310,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain);
  *
  * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  *
- * \param haptic the SDL_Haptic device to set autocentering on
- * \param autocenter value to set autocenter to (0-100)
+ * \param haptic the SDL_Haptic device to set autocentering on.
+ * \param autocenter value to set autocenter to (0-100).
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1328,7 +1330,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int
  * Do not modify the effects nor add new ones while the device is paused. That
  * can cause all sorts of weird errors.
  *
- * \param haptic the SDL_Haptic device to pause
+ * \param haptic the SDL_Haptic device to pause.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1343,7 +1345,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic);
  *
  * Call to unpause after SDL_PauseHaptic().
  *
- * \param haptic the SDL_Haptic device to unpause
+ * \param haptic the SDL_Haptic device to unpause.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1356,7 +1358,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic);
 /**
  * Stop all the currently playing effects on a haptic device.
  *
- * \param haptic the SDL_Haptic device to stop
+ * \param haptic the SDL_Haptic device to stop.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1370,7 +1372,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic);
 /**
  * Check whether rumble is supported on a haptic device.
  *
- * \param haptic haptic device to check for rumble support
+ * \param haptic haptic device to check for rumble support.
  * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1382,7 +1384,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *hapti
 /**
  * Initialize a haptic device for simple rumble playback.
  *
- * \param haptic the haptic device to initialize for simple rumble playback
+ * \param haptic the haptic device to initialize for simple rumble playback.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1397,9 +1399,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic);
 /**
  * Run a simple rumble effect on a haptic device.
  *
- * \param haptic the haptic device to play the rumble effect on
- * \param strength strength of the rumble to play as a 0-1 float value
- * \param length length of the rumble to play in milliseconds
+ * \param haptic the haptic device to play the rumble effect on.
+ * \param strength strength of the rumble to play as a 0-1 float value.
+ * \param length length of the rumble to play in milliseconds.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1413,7 +1415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float s
 /**
  * Stop the simple rumble on a haptic device.
  *
- * \param haptic the haptic device to stop the rumble effect on
+ * \param haptic the haptic device to stop the rumble effect on.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_hidapi.h

@@ -225,9 +225,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
  * or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS
  * can be set to "0" to enumerate all HID devices.
  *
- * \param vendor_id The Vendor ID (VID) of the types of device to open, or 0
+ * \param vendor_id the Vendor ID (VID) of the types of device to open, or 0
  *                  to match any vendor.
- * \param product_id The Product ID (PID) of the types of device to open, or 0
+ * \param product_id the Product ID (PID) of the types of device to open, or 0
  *                   to match any product.
  * \returns a pointer to a linked list of type SDL_hid_device_info, containing
  *          information about the HID devices attached to the system, or NULL
@@ -245,7 +245,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho
  *
  * This function frees a linked list created by SDL_hid_enumerate().
  *
- * \param devs Pointer to a list of struct_device returned from
+ * \param devs pointer to a list of struct_device returned from
  *             SDL_hid_enumerate().
  *
  * \since This function is available since SDL 3.0.0.
@@ -259,9 +259,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
  * If `serial_number` is NULL, the first device with the specified VID and PID
  * is opened.
  *
- * \param vendor_id The Vendor ID (VID) of the device to open.
- * \param product_id The Product ID (PID) of the device to open.
- * \param serial_number The Serial Number of the device to open (Optionally
+ * \param vendor_id the Vendor ID (VID) of the device to open.
+ * \param product_id the Product ID (PID) of the device to open.
+ * \param serial_number the Serial Number of the device to open (Optionally
  *                      NULL).
  * \returns a pointer to a SDL_hid_device object on success or NULL on
  *          failure.
@@ -276,7 +276,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
  * The path name be determined by calling SDL_hid_enumerate(), or a
  * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
  *
- * \param path The path name of the device to open
+ * \param path the path name of the device to open.
  * \returns a pointer to a SDL_hid_device object on success or NULL on
  *          failure.
  *
@@ -300,10 +300,10 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path)
  * exists. If it does not, it will send the data through the Control Endpoint
  * (Endpoint 0).
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data The data to send, including the report number as the first
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data the data to send, including the report number as the first
  *             byte.
- * \param length The length in bytes of the data to send.
+ * \param length the length in bytes of the data to send.
  * \returns the actual number of bytes written and -1 on error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -317,9 +317,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
  * The first byte will contain the Report number if the device uses numbered
  * reports.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data A buffer to put the read data into.
- * \param length The number of bytes to read. For devices with multiple
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data a buffer to put the read data into.
+ * \param length the number of bytes to read. For devices with multiple
  *               reports, make sure to read an extra byte for the report
  *               number.
  * \param milliseconds timeout in milliseconds or -1 for blocking wait.
@@ -338,9 +338,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
  * The first byte will contain the Report number if the device uses numbered
  * reports.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data A buffer to put the read data into.
- * \param length The number of bytes to read. For devices with multiple
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data a buffer to put the read data into.
+ * \param length the number of bytes to read. For devices with multiple
  *               reports, make sure to read an extra byte for the report
  *               number.
  * \returns the actual number of bytes read and -1 on error. If no packet was
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char
  *
  * Nonblocking can be turned on and off at any time.
  *
- * \param dev A device handle returned from SDL_hid_open().
+ * \param dev a device handle returned from SDL_hid_open().
  * \param nonblock enable or not the nonblocking reads - 1 to enable
  *                 nonblocking - 0 to disable nonblocking.
  * \returns 0 on success or a negative error code on failure; call
@@ -383,10 +383,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
  * devices which do not use numbered reports), followed by the report data (16
  * bytes). In this example, the length passed in would be 17.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data The data to send, including the report number as the first
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data the data to send, including the report number as the first
  *             byte.
- * \param length The length in bytes of the data to send, including the report
+ * \param length the length in bytes of the data to send, including the report
  *               number.
  * \returns the actual number of bytes written and -1 on error.
  *
@@ -402,12 +402,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
  * first byte will still contain the Report ID, and the report data will start
  * in data[1].
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data A buffer to put the read data into, including the Report ID.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data a buffer to put the read data into, including the Report ID.
  *             Set the first byte of `data` to the Report ID of the report to
  *             be read, or set it to zero if your device does not use numbered
  *             reports.
- * \param length The number of bytes to read, including an extra byte for the
+ * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
  *          still in the first byte), or -1 on error.
@@ -424,12 +424,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
  * first byte will still contain the Report ID, and the report data will start
  * in data[1].
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param data A buffer to put the read data into, including the Report ID.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param data a buffer to put the read data into, including the Report ID.
  *             Set the first byte of `data` to the Report ID of the report to
  *             be read, or set it to zero if your device does not use numbered
  *             reports.
- * \param length The number of bytes to read, including an extra byte for the
+ * \param length the number of bytes to read, including an extra byte for the
  *               report ID. The buffer can be longer than the actual report.
  * \returns the number of bytes read plus one for the report ID (which is
  *          still in the first byte), or -1 on error.
@@ -441,7 +441,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un
 /**
  * Close a HID device.
  *
- * \param dev A device handle returned from SDL_hid_open().
+ * \param dev a device handle returned from SDL_hid_open().
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -452,9 +452,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev);
 /**
  * Get The Manufacturer String from a HID device.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param string A wide string buffer to put the data into.
- * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param string a wide string buffer to put the data into.
+ * \param maxlen the length of the buffer in multiples of wchar_t.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -465,9 +465,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *
 /**
  * Get The Product String from a HID device.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param string A wide string buffer to put the data into.
- * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param string a wide string buffer to put the data into.
+ * \param maxlen the length of the buffer in multiples of wchar_t.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -478,9 +478,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev,
 /**
  * Get The Serial Number String from a HID device.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param string A wide string buffer to put the data into.
- * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param string a wide string buffer to put the data into.
+ * \param maxlen the length of the buffer in multiples of wchar_t.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -491,10 +491,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device
 /**
  * Get a string from a HID device, based on its string index.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param string_index The index of the string to get.
- * \param string A wide string buffer to put the data into.
- * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param string_index the index of the string to get.
+ * \param string a wide string buffer to put the data into.
+ * \param maxlen the length of the buffer in multiples of wchar_t.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -505,7 +505,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
 /**
  * Get the device info from a HID device.
  *
- * \param dev A device handle returned from SDL_hid_open().
+ * \param dev a device handle returned from SDL_hid_open().
  * \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL
  *          in the case of failure; call SDL_GetError() for more information.
  *          This struct is valid until the device is closed with
@@ -521,9 +521,9 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi
  * User has to provide a preallocated buffer where descriptor will be copied
  * to. The recommended size for a preallocated buffer is 4096 bytes.
  *
- * \param dev A device handle returned from SDL_hid_open().
- * \param buf The buffer to copy descriptor into.
- * \param buf_size The size of the buffer in bytes.
+ * \param dev a device handle returned from SDL_hid_open().
+ * \param buf the buffer to copy descriptor into.
+ * \param buf_size the size of the buffer in bytes.
  * \returns the number of bytes actually copied, or -1 on error; call
  *          SDL_GetError() for more information.
  *
@@ -534,7 +534,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *de
 /**
  * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
  *
- * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan
+ * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_hints.h

@@ -3755,9 +3755,9 @@ typedef enum SDL_HintPriority
  * value. Hints will replace existing hints of their priority and lower.
  * Environment variables are considered to have override priority.
  *
- * \param name the hint to set
- * \param value the value of the hint variable
- * \param priority the SDL_HintPriority level for the hint
+ * \param name the hint to set.
+ * \param value the value of the hint variable.
+ * \param priority the SDL_HintPriority level for the hint.
  * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -3777,8 +3777,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
  * variable that takes precedence. You can use SDL_SetHintWithPriority() to
  * set the hint with override priority instead.
  *
- * \param name the hint to set
- * \param value the value of the hint variable
+ * \param name the hint to set.
+ * \param value the value of the hint variable.
  * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -3797,7 +3797,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
  * the environment isn't set. Callbacks will be called normally with this
  * change.
  *
- * \param name the hint to set
+ * \param name the hint to set.
  * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -3825,7 +3825,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param name the hint to query
+ * \param name the hint to query.
  * \returns the string value of a hint or NULL if the hint isn't set.
  *
  * \since This function is available since SDL 3.0.0.
@@ -3838,8 +3838,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
 /**
  * Get the boolean value of a hint variable.
  *
- * \param name the name of the hint to get the boolean value from
- * \param default_value the value to return if the hint does not exist
+ * \param name the name of the hint to get the boolean value from.
+ * \param default_value the value to return if the hint does not exist.
  * \returns the boolean value of a hint or the provided default value if the
  *          hint does not exist.
  *
@@ -3853,10 +3853,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo
 /**
  * Type definition of the hint callback function.
  *
- * \param userdata what was passed as `userdata` to SDL_AddHintCallback()
- * \param name what was passed as `name` to SDL_AddHintCallback()
- * \param oldValue the previous hint value
- * \param newValue the new value hint is to be set to
+ * \param userdata what was passed as `userdata` to SDL_AddHintCallback().
+ * \param name what was passed as `name` to SDL_AddHintCallback().
+ * \param oldValue the previous hint value.
+ * \param newValue the new value hint is to be set to.
  *
  * \since This datatype is available since SDL 3.0.0.
  */
@@ -3865,10 +3865,10 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const
 /**
  * Add a function to watch a particular hint.
  *
- * \param name the hint to watch
- * \param callback An SDL_HintCallback function that will be called when the
- *                 hint value changes
- * \param userdata a pointer to pass to the callback function
+ * \param name the hint to watch.
+ * \param callback an SDL_HintCallback function that will be called when the
+ *                 hint value changes.
+ * \param userdata a pointer to pass to the callback function.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -3886,10 +3886,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddHintCallback(const char *name,
 /**
  * Remove a function watching a particular hint.
  *
- * \param name the hint being watched
- * \param callback An SDL_HintCallback function that will be called when the
- *                 hint value changes
- * \param userdata a pointer being passed to the callback function
+ * \param name the hint being watched.
+ * \param callback an SDL_HintCallback function that will be called when the
+ *                 hint value changes.
+ * \param userdata a pointer being passed to the callback function.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_init.h

@@ -105,7 +105,7 @@ typedef Uint32 SDL_InitFlags;
  * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
  * this call will increase the ref-count and return.
  *
- * \param flags subsystem initialization flags
+ * \param flags subsystem initialization flags.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_iostream.h

@@ -221,7 +221,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  *   the filesystem. If SDL used some other method to access the filesystem,
  *   this property will not be set.
  *
- * \param file a UTF-8 string representing the filename to open
+ * \param file a UTF-8 string representing the filename to open.
  * \param mode an ASCII string representing the mode to be used for opening
  *             the file.
  * \returns a pointer to the SDL_IOStream structure that is created, or NULL
@@ -256,8 +256,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromFile(const char *file, const
  * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of
  * memory instead.
  *
- * \param mem a pointer to a buffer to feed an SDL_IOStream stream
- * \param size the buffer size, in bytes
+ * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
+ * \param size the buffer size, in bytes.
  * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
  *          call SDL_GetError() for more information.
  *
@@ -289,8 +289,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromMem(void *mem, size_t size);
  * If you need to write to a memory buffer, you should use SDL_IOFromMem()
  * with a writable buffer of memory instead.
  *
- * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream
- * \param size the buffer size, in bytes
+ * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
+ * \param size the buffer size, in bytes.
  * \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
  *          call SDL_GetError() for more information.
  *
@@ -351,8 +351,8 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
  * This function makes a copy of `iface` and the caller does not need to keep
  * this data around after this call.
  *
- * \param iface The function pointers that implement this SDL_IOStream.
- * \param userdata The app-controlled pointer that is passed to iface's
+ * \param iface the function pointers that implement this SDL_IOStream.
+ * \param userdata the app-controlled pointer that is passed to iface's
  *                 functions when called.
  * \returns a pointer to the allocated memory on success, or NULL on failure;
  *          call SDL_GetError() for more information.
@@ -377,7 +377,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_OpenIO(const SDL_IOStreamInterface
  * Note that if this fails to flush the stream to disk, this function reports
  * an error, but the SDL_IOStream is still invalid once this function returns.
  *
- * \param context SDL_IOStream structure to close
+ * \param context SDL_IOStream structure to close.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -390,7 +390,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CloseIO(SDL_IOStream *context);
 /**
  * Get the properties associated with an SDL_IOStream.
  *
- * \param context a pointer to an SDL_IOStream structure
+ * \param context a pointer to an SDL_IOStream structure.
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -425,7 +425,7 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context);
 /**
  * Use this function to get the size of the data stream in an SDL_IOStream.
  *
- * \param context the SDL_IOStream to get the size of the data stream from
+ * \param context the SDL_IOStream to get the size of the data stream from.
  * \returns the size of the data stream in the SDL_IOStream on success or a
  *          negative error code on failure; call SDL_GetError() for more
  *          information.
@@ -447,11 +447,11 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context);
  *
  * If this stream can not seek, it will return -1.
  *
- * \param context a pointer to an SDL_IOStream structure
+ * \param context a pointer to an SDL_IOStream structure.
  * \param offset an offset in bytes, relative to `whence` location; can be
- *               negative
+ *               negative.
  * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`,
- *               `SDL_IO_SEEK_END`
+ *               `SDL_IO_SEEK_END`.
  * \returns the final offset in the data stream after the seek or a negative
  *          error code on failure; call SDL_GetError() for more information.
  *
@@ -469,7 +469,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs
  * simplify application development.
  *
  * \param context an SDL_IOStream data stream object from which to get the
- *                current offset
+ *                current offset.
  * \returns the current offset in the stream, or -1 if the information can not
  *          be determined.
  *
@@ -488,8 +488,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
  * determine if there was an error or all data was read, call
  * SDL_GetIOStatus().
  *
- * \param context a pointer to an SDL_IOStream structure
- * \param ptr a pointer to a buffer to read data into
+ * \param context a pointer to an SDL_IOStream structure.
+ * \param ptr a pointer to a buffer to read data into.
  * \param size the number of bytes to read from the data source.
  * \returns the number of bytes read, or 0 on end of file or other error.
  *
@@ -514,9 +514,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr,
  * recoverable, such as a non-blocking write that can simply be retried later,
  * or a fatal error.
  *
- * \param context a pointer to an SDL_IOStream structure
- * \param ptr a pointer to a buffer containing data to write
- * \param size the number of bytes to write
+ * \param context a pointer to an SDL_IOStream structure.
+ * \param ptr a pointer to a buffer containing data to write.
+ * \param size the number of bytes to write.
  * \returns the number of bytes written, which will be less than `size` on
  *          error; call SDL_GetError() for more information.
  *
@@ -534,10 +534,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void
  *
  * This function does formatted printing to the stream.
  *
- * \param context a pointer to an SDL_IOStream structure
- * \param fmt a printf() style format string
+ * \param context a pointer to an SDL_IOStream structure.
+ * \param fmt a printf() style format string.
  * \param ... additional parameters matching % tokens in the `fmt` string, if
- *            any
+ *            any.
  * \returns the number of bytes written, or 0 on error; call SDL_GetError()
  *          for more information.
  *
@@ -553,9 +553,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT
  *
  * This function does formatted printing to the stream.
  *
- * \param context a pointer to an SDL_IOStream structure
- * \param fmt a printf() style format string
- * \param ap a variable argument list
+ * \param context a pointer to an SDL_IOStream structure.
+ * \param fmt a printf() style format string.
+ * \param ap a variable argument list.
  * \returns the number of bytes written, or 0 on error; call SDL_GetError()
  *          for more information.
  *
@@ -575,10 +575,10 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
  *
  * The data should be freed with SDL_free().
  *
- * \param src the SDL_IOStream to read all available data from
- * \param datasize if not NULL, will store the number of bytes read
+ * \param src the SDL_IOStream to read all available data from.
+ * \param datasize if not NULL, will store the number of bytes read.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
- *                even in the case of an error
+ *                even in the case of an error.
  * \returns the data, or NULL if there was an error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -596,8 +596,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *dat
  *
  * The data should be freed with SDL_free().
  *
- * \param file the path to read all available data from
- * \param datasize if not NULL, will store the number of bytes read
+ * \param file the path to read all available data from.
+ * \param datasize if not NULL, will store the number of bytes read.
  * \returns the data, or NULL if there was an error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -616,8 +616,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasiz
 /**
  * Use this function to read a byte from an SDL_IOStream.
  *
- * \param src the SDL_IOStream to read from
- * \param value a pointer filled in with the data read
+ * \param src the SDL_IOStream to read from.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
  *          for more information.
  *
@@ -628,8 +628,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value)
 /**
  * Use this function to read a signed byte from an SDL_IOStream.
  *
- * \param src the SDL_IOStream to read from
- * \param value a pointer filled in with the data read
+ * \param src the SDL_IOStream to read from.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
  *          for more information.
  *
@@ -644,8 +644,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -660,8 +660,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -676,8 +676,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -692,8 +692,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -708,8 +708,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -724,8 +724,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -740,8 +740,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -756,8 +756,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -772,8 +772,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -788,8 +788,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -804,8 +804,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -820,8 +820,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va
  * SDL byteswaps the data only if necessary, so the data returned will be in
  * the native byte order.
  *
- * \param src the stream from which to read data
- * \param value a pointer filled in with the data read
+ * \param src the stream from which to read data.
+ * \param value a pointer filled in with the data read.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -840,8 +840,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va
 /**
  * Use this function to write a byte to an SDL_IOStream.
  *
- * \param dst the SDL_IOStream to write to
- * \param value the byte value to write
+ * \param dst the SDL_IOStream to write to.
+ * \param value the byte value to write.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -852,8 +852,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
 /**
  * Use this function to write a signed byte to an SDL_IOStream.
  *
- * \param dst the SDL_IOStream to write to
- * \param value the byte value to write
+ * \param dst the SDL_IOStream to write to.
+ * \param value the byte value to write.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -869,8 +869,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -886,8 +886,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -902,8 +902,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -918,8 +918,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -935,8 +935,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -952,8 +952,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -968,8 +968,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -984,8 +984,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1001,8 +1001,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1018,8 +1018,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va
  * specifies native format, and the data written will be in little-endian
  * format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1034,8 +1034,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1050,8 +1050,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va
  * SDL byteswaps the data only if necessary, so the application always
  * specifies native format, and the data written will be in big-endian format.
  *
- * \param dst the stream to which data will be written
- * \param value the data to be written, in native format
+ * \param dst the stream to which data will be written.
+ * \param value the data to be written, in native format.
  * \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_joystick.h

@@ -210,7 +210,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
 /**
  * Get a list of currently connected joysticks.
  *
- * \param count a pointer filled in with the number of joysticks returned
+ * \param count a pointer filled in with the number of joysticks returned.
  * \returns a 0 terminated array of joystick instance IDs which should be
  *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
  *          more details.
@@ -229,7 +229,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetJoysticks(int *count);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the name of the selected joystick. If no name can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -247,7 +247,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickInstanceName(SDL_Joystick
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the path of the selected joystick. If no path can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -263,8 +263,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickInstancePath(SDL_Joystick
  *
  * This can be called before any joysticks are opened.
  *
- * \param instance_id the joystick instance ID
- * \returns the player index of a joystick, or -1 if it's not available
+ * \param instance_id the joystick instance ID.
+ * \returns the player index of a joystick, or -1 if it's not available.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -278,7 +278,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickInstancePlayerIndex(SDL_JoystickI
  *
  * This can be called before any joysticks are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the GUID of the selected joystick. If called with an invalid
  *          instance_id, this function returns a zero GUID.
  *
@@ -295,7 +295,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickInstanceGUID(SDL_Joy
  * This can be called before any joysticks are opened. If the vendor ID isn't
  * available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the USB vendor ID of the selected joystick. If called with an
  *          invalid instance_id, this function returns 0.
  *
@@ -312,7 +312,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceVendor(SDL_JoystickID
  * This can be called before any joysticks are opened. If the product ID isn't
  * available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the USB product ID of the selected joystick. If called with an
  *          invalid instance_id, this function returns 0.
  *
@@ -329,7 +329,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProduct(SDL_JoystickID
  * This can be called before any joysticks are opened. If the product version
  * isn't available this function returns 0.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the product version of the selected joystick. If called with an
  *          invalid instance_id, this function returns 0.
  *
@@ -345,7 +345,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickInstanceProductVersion(SDL_Joy
  *
  * This can be called before any joysticks are opened.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns the SDL_JoystickType of the selected joystick. If called with an
  *          invalid instance_id, this function returns
  *          `SDL_JOYSTICK_TYPE_UNKNOWN`.
@@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickInstanceType(SDL_Joy
  * The joystick subsystem must be initialized before a joystick can be opened
  * for use.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns a joystick identifier or NULL if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -376,7 +376,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instan
 /**
  * Get the SDL_Joystick associated with an instance ID, if it has been opened.
  *
- * \param instance_id the instance ID to get the SDL_Joystick for
+ * \param instance_id the instance ID to get the SDL_Joystick for.
  * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
  *          opened yet; call SDL_GetError() for more information.
  *
@@ -387,7 +387,7 @@ extern SDL_DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromInstanceID(SDL_Joys
 /**
  * Get the SDL_Joystick associated with a player index.
  *
- * \param player_index the player index to get the SDL_Joystick for
+ * \param player_index the player index to get the SDL_Joystick for.
  * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
  *          for more information.
  *
@@ -469,7 +469,7 @@ typedef struct SDL_VirtualJoystickDesc
 /**
  * Attach a new virtual joystick.
  *
- * \param desc Joystick description
+ * \param desc joystick description.
  * \returns the joystick instance ID, or 0 if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -483,7 +483,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V
  * Detach a virtual joystick.
  *
  * \param instance_id the joystick instance ID, previously returned from
- *                    SDL_AttachVirtualJoystick()
+ *                    SDL_AttachVirtualJoystick().
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -496,7 +496,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instanc
 /**
  * Query whether or not a joystick is virtual.
  *
- * \param instance_id the joystick instance ID
+ * \param instance_id the joystick instance ID.
  * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -598,12 +598,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick
  *                 update.
  * \param finger the index of the finger on the touchpad to set.
  * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the
- *              finger is released
+ *              finger is released.
  * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1,
- *          with the origin in the upper left
+ *          with the origin in the upper left.
  * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1,
- *          with the origin in the upper left
- * \param pressure the pressure of the finger
+ *          with the origin in the upper left.
+ * \param pressure the pressure of the finger.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -623,9 +623,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joy
  * \param joystick the virtual joystick on which to set state.
  * \param type the type of the sensor on the virtual joystick to update.
  * \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with
- *                         the sensor reading
- * \param data the data associated with the sensor reading
- * \param num_values the number of values pointed to by `data`
+ *                         the sensor reading.
+ * \param data the data associated with the sensor reading.
+ * \param num_values the number of values pointed to by `data`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -649,7 +649,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *
  * - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has
  *   simple trigger rumble
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -671,7 +671,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the name of the selected joystick. If no name can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -686,7 +686,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickName(SDL_Joystick *joysti
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the path of the selected joystick. If no path can be found, this
  *          function returns NULL; call SDL_GetError() for more information.
  *
@@ -702,7 +702,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickPath(SDL_Joystick *joysti
  * For XInput controllers this returns the XInput user index. Many joysticks
  * will not be able to supply this information.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the player index, or -1 if it's not available.
  *
  * \since This function is available since SDL 3.0.0.
@@ -714,8 +714,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic
 /**
  * Set the player index of an opened joystick.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
- * \param player_index Player index to assign to this joystick, or -1 to clear
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
+ * \param player_index player index to assign to this joystick, or -1 to clear
  *                     the player index and turn off player LEDs.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
@@ -731,7 +731,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystic
  *
  * This function requires an open joystick.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the GUID of the given joystick. If called on an invalid index,
  *          this function returns a zero GUID; call SDL_GetError() for more
  *          information.
@@ -748,7 +748,7 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *j
  *
  * If the vendor ID isn't available this function returns 0.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
@@ -762,7 +762,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick)
  *
  * If the product ID isn't available this function returns 0.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the USB product ID of the selected joystick, or 0 if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
@@ -776,7 +776,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick
  *
  * If the product version isn't available this function returns 0.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the product version of the selected joystick, or 0 if unavailable.
  *
  * \since This function is available since SDL 3.0.0.
@@ -790,7 +790,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j
  *
  * If the firmware version isn't available this function returns 0.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the firmware version of the selected joystick, or 0 if
  *          unavailable.
  *
@@ -805,7 +805,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the serial number of the selected joystick, or NULL if
  *          unavailable.
  *
@@ -816,7 +816,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
 /**
  * Get the type of an opened joystick.
  *
- * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
  * \returns the SDL_JoystickType of the selected joystick.
  *
  * \since This function is available since SDL 3.0.0.
@@ -830,9 +830,9 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j
  *
  * You should supply at least 33 bytes for pszGUID.
  *
- * \param guid the SDL_JoystickGUID you wish to convert to string
- * \param pszGUID buffer in which to write the ASCII string
- * \param cbGUID the size of pszGUID
+ * \param guid the SDL_JoystickGUID you wish to convert to string.
+ * \param pszGUID buffer in which to write the ASCII string.
+ * \param cbGUID the size of pszGUID.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -851,7 +851,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid,
  * an invalid GUID, the function will silently succeed, but the GUID generated
  * will not be useful.
  *
- * \param pchGUID string containing an ASCII representation of a GUID
+ * \param pchGUID string containing an ASCII representation of a GUID.
  * \returns a SDL_JoystickGUID structure.
  *
  * \since This function is available since SDL 3.0.0.
@@ -863,15 +863,15 @@ extern SDL_DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUIDFromString(const
 /**
  * Get the device information encoded in a SDL_JoystickGUID structure.
  *
- * \param guid the SDL_JoystickGUID you wish to get info about
- * \param vendor A pointer filled in with the device VID, or 0 if not
- *               available
- * \param product A pointer filled in with the device PID, or 0 if not
- *                available
- * \param version A pointer filled in with the device version, or 0 if not
- *                available
- * \param crc16 A pointer filled in with a CRC used to distinguish different
- *              products with the same VID/PID, or 0 if not available
+ * \param guid the SDL_JoystickGUID you wish to get info about.
+ * \param vendor a pointer filled in with the device VID, or 0 if not
+ *               available.
+ * \param product a pointer filled in with the device PID, or 0 if not
+ *                available.
+ * \param version a pointer filled in with the device version, or 0 if not
+ *                available.
+ * \param crc16 a pointer filled in with a CRC used to distinguish different
+ *              products with the same VID/PID, or 0 if not available.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -882,7 +882,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid,
 /**
  * Get the status of a specified joystick.
  *
- * \param joystick the joystick to query
+ * \param joystick the joystick to query.
  * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
  *          call SDL_GetError() for more information.
  *
@@ -893,7 +893,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic
 /**
  * Get the instance ID of an opened joystick.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \returns the instance ID of the specified joystick on success or 0 on
  *          failure; call SDL_GetError() for more information.
  *
@@ -908,7 +908,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickInstanceID(SDL_Joystic
  * separate buttons or a POV hat, and not axes, but all of this is up to the
  * device and platform.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \returns the number of axis controls/number of axes on success or a
  *          negative error code on failure; call SDL_GetError() for more
  *          information.
@@ -930,7 +930,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick);
  *
  * Most joysticks do not have trackballs.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \returns the number of trackballs on success or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *
@@ -946,7 +946,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick);
 /**
  * Get the number of POV hats on a joystick.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \returns the number of POV hats on success or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *
@@ -962,7 +962,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick);
 /**
  * Get the number of buttons on a joystick.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \returns the number of buttons on success or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *
@@ -982,7 +982,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick
  * yourself and check the state of the joystick when you want joystick
  * information.
  *
- * \param enabled whether to process joystick events or not
+ * \param enabled whether to process joystick events or not.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1030,8 +1030,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
  * 32767) representing the current position of the axis. It may be necessary
  * to impose certain tolerances on these values to account for jitter.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
- * \param axis the axis to query; the axis indices start at index 0
+ * \param joystick an SDL_Joystick structure containing joystick information.
+ * \param axis the axis to query; the axis indices start at index 0.
  * \returns a 16-bit signed integer representing the current position of the
  *          axis or 0 on failure; call SDL_GetError() for more information.
  *
@@ -1048,9 +1048,9 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i
  *
  * The axis indices start at index 0.
  *
- * \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.
+ * \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.
  * \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.
@@ -1065,10 +1065,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic
  *
  * Most joysticks do not have trackballs.
  *
- * \param joystick the SDL_Joystick to query
- * \param ball the ball index to query; ball indices start at index 0
- * \param dx stores the difference in the x axis position since the last poll
- * \param dy stores the difference in the y axis position since the last poll
+ * \param joystick the SDL_Joystick to query.
+ * \param ball the ball index to query; ball indices start at index 0.
+ * \param dx stores the difference in the x axis position since the last poll.
+ * \param dy stores the difference in the y axis position since the last poll.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1083,8 +1083,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int
  *
  * The returned value will be one of the `SDL_HAT_*` values.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
- * \param hat the hat index to get the state from; indices start at index 0
+ * \param joystick an SDL_Joystick structure containing joystick information.
+ * \param hat the hat index to get the state from; indices start at index 0.
  * \returns the current hat position.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1106,9 +1106,9 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int
 /**
  * Get the current state of a button on a joystick.
  *
- * \param joystick an SDL_Joystick structure containing joystick information
+ * \param joystick an SDL_Joystick structure containing joystick information.
  * \param button the button index to get the state from; indices start at
- *               index 0
+ *               index 0.
  * \returns 1 if the specified button is pressed, 0 otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -1126,13 +1126,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
  * This function requires you to process SDL events or call
  * SDL_UpdateJoysticks() to update rumble state.
  *
- * \param joystick The joystick to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left)
- *                             rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right)
- *                              rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if rumble isn't supported on this joystick
+ * \param joystick the joystick to vibrate.
+ * \param low_frequency_rumble the intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF.
+ * \param high_frequency_rumble the intensity of the high frequency (right)
+ *                              rumble motor, from 0 to 0xFFFF.
+ * \param duration_ms the duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if rumble isn't supported on this joystick.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -1152,12 +1152,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint1
  * This function requires you to process SDL events or call
  * SDL_UpdateJoysticks() to update rumble state.
  *
- * \param joystick The joystick to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0
- *                    to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0
- *                     to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \param joystick the joystick to vibrate.
+ * \param left_rumble the intensity of the left trigger rumble motor, from 0
+ *                    to 0xFFFF.
+ * \param right_rumble the intensity of the right trigger rumble motor, from 0
+ *                     to 0xFFFF.
+ * \param duration_ms the duration of the rumble effect, in milliseconds.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1176,10 +1176,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystic
  * For joysticks with a single color LED, the maximum of the RGB values will
  * be used as the LED brightness.
  *
- * \param joystick The joystick to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
+ * \param joystick the joystick to update.
+ * \param red the intensity of the red LED.
+ * \param green the intensity of the green LED.
+ * \param blue the intensity of the blue LED.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1190,9 +1190,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8
 /**
  * Send a joystick specific effect packet.
  *
- * \param joystick The joystick to affect
- * \param data The data to send to the joystick
- * \param size The size of the data to send to the joystick
+ * \param joystick the joystick to affect.
+ * \param data the data to send to the joystick.
+ * \param size the size of the data to send to the joystick.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1203,7 +1203,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, c
 /**
  * Close a joystick previously opened with SDL_OpenJoystick().
  *
- * \param joystick The joystick device to close
+ * \param joystick the joystick device to close.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1214,7 +1214,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick);
 /**
  * Get the connection state of a joystick.
  *
- * \param joystick The joystick to query
+ * \param joystick the joystick to query.
  * \returns the connection state on success or
  *          `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
  *          for more information.
@@ -1232,7 +1232,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio
  * not uncommon for older batteries to lose stored power much faster than it
  * reports, or completely drain when reporting it has 20 percent left, etc.
  *
- * \param joystick The joystick to query
+ * \param joystick the joystick to query.
  * \param percent a pointer filled in with the percentage of battery life
  *                left, between 0 and 100, or NULL to ignore. This will be
  *                filled in with -1 we can't determine a value or there is no

include/SDL3/SDL_keyboard.h

@@ -92,7 +92,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
  * power buttons, etc. You should wait for input from a device before you
  * consider it actively in use.
  *
- * \param count a pointer filled in with the number of keyboards returned
+ * \param count a pointer filled in with the number of keyboards returned.
  * \returns a 0 terminated array of keyboards instance IDs which should be
  *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
  *          more details.
@@ -111,7 +111,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the keyboard instance ID
+ * \param instance_id the keyboard instance ID.
  * \returns the name of the selected keyboard, or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -151,7 +151,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
  * Note: This function doesn't take into account whether shift has been
  * pressed or not.
  *
- * \param numkeys if non-NULL, receives the length of the returned array
+ * \param numkeys if non-NULL, receives the length of the returned array.
  * \returns a pointer to an array of key states.
  *
  * \since This function is available since SDL 3.0.0.
@@ -196,7 +196,7 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
  * This does not change the keyboard state, only the key modifier flags that
  * SDL reports.
  *
- * \param modstate the desired SDL_Keymod for the keyboard
+ * \param modstate the desired SDL_Keymod for the keyboard.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -210,7 +210,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
  *
  * See SDL_Keycode for details.
  *
- * \param scancode the desired SDL_Scancode to query
+ * \param scancode the desired SDL_Scancode to query.
  * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
  * \since This function is available since SDL 3.0.0.
@@ -226,7 +226,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetDefaultKeyFromScancode(SDL_Scanco
  *
  * See SDL_Keycode for details.
  *
- * \param scancode the desired SDL_Scancode to query
+ * \param scancode the desired SDL_Scancode to query.
  * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
  * \since This function is available since SDL 3.0.0.
@@ -242,7 +242,7 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan
  *
  * See SDL_Scancode for details.
  *
- * \param key the desired SDL_Keycode to query
+ * \param key the desired SDL_Keycode to query.
  * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
  *
  * \since This function is available since SDL 3.0.0.
@@ -268,7 +268,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key)
  * unsuitable for creating a stable cross-platform two-way mapping between
  * strings and scancodes.
  *
- * \param scancode the desired SDL_Scancode to query
+ * \param scancode the desired SDL_Scancode to query.
  * \returns a pointer to the name for the scancode. If the scancode doesn't
  *          have a name this function returns an empty string ("").
  *
@@ -282,7 +282,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancod
 /**
  * Get a scancode from a human-readable name.
  *
- * \param name the human-readable scancode name
+ * \param name the human-readable scancode name.
  * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
  *          recognized; call SDL_GetError() for more information.
  *
@@ -301,7 +301,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param key the desired SDL_Keycode to query
+ * \param key the desired SDL_Keycode to query.
  * \returns a pointer to a UTF-8 string that stays valid at least until the
  *          next call to this function. If you need it around any longer, you
  *          must copy it. If the key doesn't have a name, this function
@@ -318,7 +318,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
 /**
  * Get a key code from a human-readable name.
  *
- * \param name the human-readable key name
+ * \param name the human-readable key name.
  * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
  *          SDL_GetError() for more information.
  *
@@ -396,7 +396,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClearComposition(void);
  * any feedback.
  *
  * \param rect the SDL_Rect structure representing the rectangle to receive
- *             text (ignored if NULL)
+ *             text (ignored if NULL).
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -422,7 +422,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 /**
  * Check whether the screen keyboard is shown for given window.
  *
- * \param window the window for which screen keyboard should be queried
+ * \param window the window for which screen keyboard should be queried.
  * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_loadso.h

@@ -55,7 +55,7 @@ extern "C" {
 /**
  * Dynamically load a shared object.
  *
- * \param sofile a system-dependent name of the object file
+ * \param sofile a system-dependent name of the object file.
  * \returns an opaque pointer to the object handle or NULL if there was an
  *          error; call SDL_GetError() for more information.
  *
@@ -81,8 +81,8 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
  *
  * If the requested function doesn't exist, NULL is returned.
  *
- * \param handle a valid shared object handle returned by SDL_LoadObject()
- * \param name the name of the function to look up
+ * \param handle a valid shared object handle returned by SDL_LoadObject().
+ * \param name the name of the function to look up.
  * \returns a pointer to the function or NULL if there was an error; call
  *          SDL_GetError() for more information.
  *
@@ -95,7 +95,7 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, c
 /**
  * Unload a shared object from memory.
  *
- * \param handle a valid shared object handle returned by SDL_LoadObject()
+ * \param handle a valid shared object handle returned by SDL_LoadObject().
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_log.h

@@ -110,7 +110,7 @@ typedef enum SDL_LogPriority
 /**
  * Set the priority of all log categories.
  *
- * \param priority the SDL_LogPriority to assign
+ * \param priority the SDL_LogPriority to assign.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -122,8 +122,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority);
 /**
  * Set the priority of a particular log category.
  *
- * \param category the category to assign a priority to
- * \param priority the SDL_LogPriority to assign
+ * \param category the category to assign a priority to.
+ * \param priority the SDL_LogPriority to assign.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -137,8 +137,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category,
 /**
  * Get the priority of a particular log category.
  *
- * \param category the category to query
- * \returns the SDL_LogPriority for the requested category
+ * \param category the category to query.
+ * \returns the SDL_LogPriority for the requested category.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -161,9 +161,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void);
 /**
  * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
  *
- * \param fmt a printf() style message format string
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the `fmt` string, if
- *            any
+ *            any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -181,10 +181,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm
 /**
  * Log a message with SDL_LOG_PRIORITY_VERBOSE.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -202,10 +202,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_
 /**
  * Log a message with SDL_LOG_PRIORITY_DEBUG.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -223,10 +223,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST
 /**
  * Log a message with SDL_LOG_PRIORITY_INFO.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -244,10 +244,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR
 /**
  * Log a message with SDL_LOG_PRIORITY_WARN.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -265,10 +265,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR
 /**
  * Log a message with SDL_LOG_PRIORITY_ERROR.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -286,10 +286,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST
 /**
  * Log a message with SDL_LOG_PRIORITY_CRITICAL.
  *
- * \param category the category of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -307,11 +307,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT
 /**
  * Log a message with the specified category and priority.
  *
- * \param category the category of the message
- * \param priority the priority of the message
- * \param fmt a printf() style message format string
+ * \param category the category of the message.
+ * \param priority the priority of the message.
+ * \param fmt a printf() style message format string.
  * \param ... additional parameters matching % tokens in the **fmt** string,
- *            if any
+ *            if any.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -331,10 +331,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category,
 /**
  * Log a message with the specified category and priority.
  *
- * \param category the category of the message
- * \param priority the priority of the message
- * \param fmt a printf() style message format string
- * \param ap a variable argument list
+ * \param category the category of the message.
+ * \param priority the priority of the message.
+ * \param fmt a printf() style message format string.
+ * \param ap a variable argument list.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -356,10 +356,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category,
  *
  * This function is called by SDL when there is new text to be logged.
  *
- * \param userdata what was passed as `userdata` to SDL_SetLogOutputFunction()
- * \param category the category of the message
- * \param priority the priority of the message
- * \param message the message being output
+ * \param userdata what was passed as `userdata` to
+ *                 SDL_SetLogOutputFunction().
+ * \param category the category of the message.
+ * \param priority the priority of the message.
+ * \param message the message being output.
  *
  * \since This datatype is available since SDL 3.0.0.
  */
@@ -369,9 +370,9 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_
  * Get the current log output function.
  *
  * \param callback an SDL_LogOutputFunction filled in with the current log
- *                 callback
+ *                 callback.
  * \param userdata a pointer filled in with the pointer that is passed to
- *                 `callback`
+ *                 `callback`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -382,8 +383,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction
 /**
  * Replace the default log output function with one of your own.
  *
- * \param callback an SDL_LogOutputFunction to call instead of the default
- * \param userdata a pointer that is passed to `callback`
+ * \param callback an SDL_LogOutputFunction to call instead of the default.
+ * \param userdata a pointer that is passed to `callback`.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_main.h

@@ -287,8 +287,8 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
  *
  * \param appstate a place where the app can optionally store a pointer for
  *                 future use.
- * \param argc The standard ANSI C main's argc; number of elements in `argv`
- * \param argv The standard ANSI C main's argv; array of command line
+ * \param argc the standard ANSI C main's argc; number of elements in `argv`.
+ * \param argv the standard ANSI C main's argv; array of command line
  *             arguments.
  * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
  *          terminate with success, SDL_APP_CONTINUE to continue.
@@ -506,17 +506,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void);
  * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do
  * *not* need SDL_SetMainReady().
  *
- * \param argc The argc parameter from the application's main() function, or 0
- *             if the platform's main-equivalent has no argc
- * \param argv The argv parameter from the application's main() function, or
- *             NULL if the platform's main-equivalent has no argv
- * \param mainFunction Your SDL app's C-style main(). NOT the function you're
+ * \param argc the argc parameter from the application's main() function, or 0
+ *             if the platform's main-equivalent has no argc.
+ * \param argv the argv parameter from the application's main() function, or
+ *             NULL if the platform's main-equivalent has no argv.
+ * \param mainFunction your SDL app's C-style main(). NOT the function you're
  *                     calling this from! Its name doesn't matter; it doesn't
  *                     literally have to be `main`.
  * \param reserved should be NULL (reserved for future use, will probably be
- *                 platform-specific then)
+ *                 platform-specific then).
  * \returns the return value from mainFunction: 0 on success, -1 on failure;
- *          SDL_GetError() might have more information on the failure
+ *          SDL_GetError() might have more information on the failure.
  *
  * \threadsafety Generally this is called once, near startup, from the
  *               process's initial thread.
@@ -537,13 +537,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func
  * header-only library, and you should not call this directly unless you
  * _really_ know what you're doing.
  *
- * \param argc standard Unix main argc
- * \param argv standard Unix main argv
- * \param appinit The application's SDL_AppInit function
- * \param appiter The application's SDL_AppIterate function
- * \param appevent The application's SDL_AppEvent function
- * \param appquit The application's SDL_AppQuit function
- * \returns standard Unix main return value
+ * \param argc standard Unix main argc.
+ * \param argv standard Unix main argv.
+ * \param appinit the application's SDL_AppInit function.
+ * \param appiter the application's SDL_AppIterate function.
+ * \param appevent the application's SDL_AppEvent function.
+ * \param appquit the application's SDL_AppQuit function.
+ * \returns standard Unix main return value.
  *
  * \threadsafety It is not safe to call this anywhere except as the only
  *               function call in SDL_main.

include/SDL3/SDL_messagebox.h

@@ -151,8 +151,9 @@ typedef struct SDL_MessageBoxData
  * to stderr if you can.
  *
  * \param messageboxdata the SDL_MessageBoxData structure with title, text and
- *                       other options
- * \param buttonid the pointer to which user id of hit button should be copied
+ *                       other options.
+ * \param buttonid the pointer to which user id of hit button should be
+ *                 copied.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -191,10 +192,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *mes
  * concern, check the return value from this function and fall back to writing
  * to stderr if you can.
  *
- * \param flags an SDL_MessageBoxFlags value
- * \param title UTF-8 title text
- * \param message UTF-8 message text
- * \param window the parent window, or NULL for no parent
+ * \param flags an SDL_MessageBoxFlags value.
+ * \param title uTF-8 title text.
+ * \param message uTF-8 message text.
+ * \param window the parent window, or NULL for no parent.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_metal.h

@@ -58,8 +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().
  *
- * \param window the window
- * \returns handle NSView or UIView
+ * \param window the window.
+ * \returns handle NSView or UIView.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -74,7 +74,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * wind
  * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
  * called after SDL_CreateWindow.
  *
- * \param view the SDL_MetalView object
+ * \param view the SDL_MetalView object.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -85,8 +85,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
 /**
  * Get a pointer to the backing CAMetalLayer for the given view.
  *
- * \param view the SDL_MetalView object
- * \returns a pointer
+ * \param view the SDL_MetalView object.
+ * \returns a pointer.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_misc.h

@@ -60,7 +60,7 @@ extern "C" {
  * All this to say: this function can be useful, but you should definitely
  * test it on every platform you target.
  *
- * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
+ * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for
  *            local files, if supported.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.

include/SDL3/SDL_mouse.h

@@ -135,7 +135,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
  * You should wait for input from a device before you consider it actively in
  * use.
  *
- * \param count a pointer filled in with the number of mice returned
+ * \param count a pointer filled in with the number of mice returned.
  * \returns a 0 terminated array of mouse instance IDs which should be freed
  *          with SDL_free(), or NULL on error; call SDL_GetError() for more
  *          details.
@@ -154,7 +154,7 @@ extern SDL_DECLSPEC SDL_MouseID *SDLCALL SDL_GetMice(int *count);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the mouse instance ID
+ * \param instance_id the mouse instance ID.
  * \returns the name of the selected mouse, or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -183,9 +183,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
  * either `x` or `y`.
  *
  * \param x the x coordinate of the mouse cursor position relative to the
- *          focus window
+ *          focus window.
  * \param y the y coordinate of the mouse cursor position relative to the
- *          focus window
+ *          focus window.
  * \returns a 32-bit button bitmask of the current button state.
  *
  * \since This function is available since SDL 3.0.0.
@@ -212,9 +212,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, flo
  * reason to use this function, you probably want SDL_GetMouseState() instead.
  *
  * \param x filled in with the current X coord relative to the desktop; can be
- *          NULL
+ *          NULL.
  * \param y filled in with the current Y coord relative to the desktop; can be
- *          NULL
+ *          NULL.
  * \returns the current button state as a bitmask which can be tested using
  *          the SDL_BUTTON(X) macros.
  *
@@ -234,8 +234,8 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *
  * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
  * event initialization. You can pass NULL for either `x` or `y`.
  *
- * \param x a pointer filled with the last recorded x coordinate of the mouse
- * \param y a pointer filled with the last recorded y coordinate of the mouse
+ * \param x a pointer filled with the last recorded x coordinate of the mouse.
+ * \param y a pointer filled with the last recorded y coordinate of the mouse.
  * \returns a 32-bit button bitmask of the relative button state.
  *
  * \since This function is available since SDL 3.0.0.
@@ -255,9 +255,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float
  * mouse when used over Microsoft Remote Desktop.
  *
  * \param window the window to move the mouse into, or NULL for the current
- *               mouse focus
- * \param x the x coordinate within the window
- * \param y the y coordinate within the window
+ *               mouse focus.
+ * \param x the x coordinate within the window.
+ * \param y the y coordinate within the window.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -277,8 +277,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
  * Note that this function will appear to succeed, but not actually move the
  * mouse when used over Microsoft Remote Desktop.
  *
- * \param x the x coordinate
- * \param y the y coordinate
+ * \param x the x coordinate.
+ * \param y the y coordinate.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -388,14 +388,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
  * Also, SDL_CreateSystemCursor() is available, which provides several
  * readily-available system cursors to pick from.
  *
- * \param data the color value for each pixel of the cursor
- * \param mask the mask value for each pixel of the cursor
- * \param w the width of the cursor
- * \param h the height of the cursor
+ * \param data the color value for each pixel of the cursor.
+ * \param mask the mask value for each pixel of the cursor.
+ * \param w the width of the cursor.
+ * \param h the height of the cursor.
  * \param hot_x the x-axis offset from the left of the cursor image to the
- *              mouse x position, in the range of 0 to `w` - 1
+ *              mouse x position, in the range of 0 to `w` - 1.
  * \param hot_y the y-axis offset from the top of the cursor image to the
- *              mouse y position, in the range of 0 to `h` - 1
+ *              mouse y position, in the range of 0 to `h` - 1.
  * \returns a new cursor with the specified parameters on success or NULL on
  *          failure; call SDL_GetError() for more information.
  *
@@ -414,9 +414,9 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
 /**
  * Create a color cursor.
  *
- * \param surface an SDL_Surface structure representing the cursor image
- * \param hot_x the x position of the cursor hot spot
- * \param hot_y the y position of the cursor hot spot
+ * \param surface an SDL_Surface structure representing the cursor image.
+ * \param hot_x the x position of the cursor hot spot.
+ * \param hot_y the y position of the cursor hot spot.
  * \returns the new cursor on success or NULL on failure; call SDL_GetError()
  *          for more information.
  *
@@ -434,7 +434,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surfa
 /**
  * Create a system cursor.
  *
- * \param id an SDL_SystemCursor enum value
+ * \param id an SDL_SystemCursor enum value.
  * \returns a cursor on success or NULL on failure; call SDL_GetError() for
  *          more information.
  *
@@ -452,7 +452,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor
  * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
  * this is desired for any reason.
  *
- * \param cursor a cursor to make active
+ * \param cursor a cursor to make active.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -494,7 +494,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
  * Use this function to free cursor resources created with SDL_CreateCursor(),
  * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
  *
- * \param cursor the cursor to free
+ * \param cursor the cursor to free.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_mutex.h

@@ -181,7 +181,7 @@ extern SDL_DECLSPEC SDL_Mutex *SDLCALL SDL_CreateMutex(void);
  * having locked nothing. If the mutex is valid, this function will always
  * block until it can lock the mutex, and return with it locked.
  *
- * \param mutex the mutex to lock
+ * \param mutex the mutex to lock.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -204,8 +204,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut
  * either lock the mutex and return 0, or return SDL_MUTEX_TIMEOUT and lock
  * nothing.
  *
- * \param mutex the mutex to try to lock
- * \returns 0 or `SDL_MUTEX_TIMEDOUT`
+ * \param mutex the mutex to try to lock.
+ * \returns 0 or `SDL_MUTEX_TIMEDOUT`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -242,7 +242,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m
  * to destroy a locked mutex, and may result in undefined behavior depending
  * on the platform.
  *
- * \param mutex the mutex to destroy
+ * \param mutex the mutex to destroy.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -360,7 +360,7 @@ extern SDL_DECLSPEC SDL_RWLock *SDLCALL SDL_CreateRWLock(void);
  * having locked nothing. If the rwlock is valid, this function will always
  * block until it can lock the mutex, and return with it locked.
  *
- * \param rwlock the read/write lock to lock
+ * \param rwlock the read/write lock to lock.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -391,7 +391,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD
  * having locked nothing. If the rwlock is valid, this function will always
  * block until it can lock the mutex, and return with it locked.
  *
- * \param rwlock the read/write lock to lock
+ * \param rwlock the read/write lock to lock.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -418,8 +418,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD
  * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
  * and lock nothing.
  *
- * \param rwlock the rwlock to try to lock
- * \returns 0 or `SDL_RWLOCK_TIMEDOUT`
+ * \param rwlock the rwlock to try to lock.
+ * \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -451,8 +451,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock)
  * always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
  * and lock nothing.
  *
- * \param rwlock the rwlock to try to lock
- * \returns 0 or `SDL_RWLOCK_TIMEDOUT`
+ * \param rwlock the rwlock to try to lock.
+ * \returns 0 or `SDL_RWLOCK_TIMEDOUT`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -496,7 +496,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS
  * is not safe to attempt to destroy a locked rwlock, and may result in
  * undefined behavior depending on the platform.
  *
- * \param rwlock the rwlock to destroy
+ * \param rwlock the rwlock to destroy.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -537,7 +537,7 @@ typedef struct SDL_Semaphore SDL_Semaphore;
  * is 0. Each post operation will atomically increment the semaphore value and
  * wake waiting threads and allow them to retry the wait operation.
  *
- * \param initial_value the starting value of the semaphore
+ * \param initial_value the starting value of the semaphore.
  * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
  *          information.
  *
@@ -558,7 +558,7 @@ extern SDL_DECLSPEC SDL_Semaphore *SDLCALL SDL_CreateSemaphore(Uint32 initial_va
  * It is not safe to destroy a semaphore if there are threads currently
  * waiting on it.
  *
- * \param sem the semaphore to destroy
+ * \param sem the semaphore to destroy.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -577,7 +577,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem);
  * This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with
  * a time length of -1.
  *
- * \param sem the semaphore wait on
+ * \param sem the semaphore wait on.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -597,7 +597,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem);
  * the semaphore doesn't have a positive value, the function immediately
  * returns SDL_MUTEX_TIMEDOUT.
  *
- * \param sem the semaphore to wait on
+ * \param sem the semaphore to wait on.
  * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
  *          block, or a negative error code on failure; call SDL_GetError()
  *          for more information.
@@ -618,8 +618,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem);
  * signal or error, or the specified time has elapsed. If the call is
  * successful it will atomically decrement the semaphore value.
  *
- * \param sem the semaphore to wait on
- * \param timeoutMS the length of the timeout, in milliseconds
+ * \param sem the semaphore to wait on.
+ * \param timeoutMS the length of the timeout, in milliseconds.
  * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
  *          succeed in the allotted time, or a negative error code on failure;
  *          call SDL_GetError() for more information.
@@ -635,7 +635,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sin
 /**
  * Atomically increment a semaphore's value and wake waiting threads.
  *
- * \param sem the semaphore to increment
+ * \param sem the semaphore to increment.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -650,7 +650,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_PostSemaphore(SDL_Semaphore *sem);
 /**
  * Get the current value of a semaphore.
  *
- * \param sem the semaphore to query
+ * \param sem the semaphore to query.
  * \returns the current value of the semaphore.
  *
  * \since This function is available since SDL 3.0.0.
@@ -699,7 +699,7 @@ extern SDL_DECLSPEC SDL_Condition *SDLCALL SDL_CreateCondition(void);
 /**
  * Destroy a condition variable.
  *
- * \param cond the condition variable to destroy
+ * \param cond the condition variable to destroy.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -710,7 +710,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond);
 /**
  * Restart one of the threads that are waiting on the condition variable.
  *
- * \param cond the condition variable to signal
+ * \param cond the condition variable to signal.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -727,7 +727,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SignalCondition(SDL_Condition *cond);
 /**
  * Restart all threads that are waiting on the condition variable.
  *
- * \param cond the condition variable to signal
+ * \param cond the condition variable to signal.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -756,8 +756,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond);
  * This function is the equivalent of calling SDL_WaitConditionTimeout() with
  * a time length of -1.
  *
- * \param cond the condition variable to wait on
- * \param mutex the mutex used to coordinate thread access
+ * \param cond the condition variable to wait on.
+ * \param mutex the mutex used to coordinate thread access.
  * \returns 0 when it is signaled or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -784,10 +784,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex
  * recursively (more than once) is not supported and leads to undefined
  * behavior.
  *
- * \param cond the condition variable to wait on
- * \param mutex the mutex used to coordinate thread access
+ * \param cond the condition variable to wait on.
+ * \param mutex the mutex used to coordinate thread access.
  * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait
- *                  indefinitely
+ *                  indefinitely.
  * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
  *          the condition is not signaled in the allotted time, or a negative
  *          error code on failure; call SDL_GetError() for more information.

include/SDL3/SDL_pen.h

@@ -154,7 +154,7 @@ typedef enum SDL_PenSubtype
  * throughout a session. To track pens across sessions (program restart), use
  * SDL_GUID .
  *
- * \param count The number of pens in the array (number of array elements
+ * \param count the number of pens in the array (number of array elements
  *              minus 1, i.e., not counting the terminator 0).
  * \returns a 0 terminated array of SDL_PenID values, or NULL on error. The
  *          array must be freed with SDL_free(). On a NULL return,
@@ -170,12 +170,12 @@ extern SDL_DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
  * If the pen is detached (cf. SDL_PenConnected), this operation may return
  * default values.
  *
- * \param instance_id The pen to query.
- * \param x Out-mode parameter for pen x coordinate. May be NULL.
- * \param y Out-mode parameter for pen y coordinate. May be NULL.
- * \param axes Out-mode parameter for axis information. May be null. The axes
+ * \param instance_id the pen to query.
+ * \param x out-mode parameter for pen x coordinate. May be NULL.
+ * \param y out-mode parameter for pen y coordinate. May be NULL.
+ * \param axes out-mode parameter for axis information. May be null. The axes
  *             are in the same order as SDL_PenAxis.
- * \param num_axes Maximum number of axes to write to "axes".
+ * \param num_axes maximum number of axes to write to "axes".
  * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK
  *          etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of
  *          SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see
@@ -188,7 +188,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float
 /**
  * Retrieves an SDL_PenID for the given SDL_GUID.
  *
- * \param guid A pen GUID.
+ * \param guid a pen GUID.
  * \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
  *          SDL_PenID.
  *
@@ -199,7 +199,7 @@ extern SDL_DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
 /**
  * Retrieves the SDL_GUID for a given SDL_PenID.
  *
- * \param instance_id The pen to query.
+ * \param instance_id the pen to query.
  * \returns the corresponding pen GUID; persistent across multiple sessions.
  *          If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
  *
@@ -213,7 +213,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
  * If a pen is detached, it will not show up for SDL_GetPens(). Other
  * operations will still be available but may return default values.
  *
- * \param instance_id A pen ID.
+ * \param instance_id a pen ID.
  * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
  *          attached, or SDL_FALSE otherwise.
  *
@@ -226,14 +226,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id The pen to query.
+ * \param instance_id the pen to query.
  * \returns a string that contains the name of the pen, intended for human
  *          consumption. The string might or might not be localised, depending
  *          on platform settings. It is not guaranteed to be unique; use
  *          SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
  *          is managed by the SDL pen subsystem and must not be deallocated.
  *          The pointer remains valid until SDL is shut down. Returns NULL on
- *          error (cf. SDL_GetError())
+ *          error (cf. SDL_GetError()).
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -254,10 +254,10 @@ typedef struct SDL_PenCapabilityInfo
 /**
  * Retrieves capability flags for a given SDL_PenID.
  *
- * \param instance_id The pen to query.
- * \param capabilities Detail information about pen capabilities, such as the
- *                     number of buttons
- * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES
+ * \param instance_id the pen to query.
+ * \param capabilities detail information about pen capabilities, such as the
+ *                     number of buttons.
+ * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -266,7 +266,7 @@ extern SDL_DECLSPEC SDL_PenCapabilityFlags SDLCALL SDL_GetPenCapabilities(SDL_Pe
 /**
  * Retrieves the pen type for a given SDL_PenID.
  *
- * \param instance_id The pen to query.
+ * \param instance_id the pen to query.
  * \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
  *          Note that the pen type does not dictate whether the pen tip is
  *          SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen

include/SDL3/SDL_pixels.h

@@ -760,7 +760,7 @@ typedef struct SDL_PixelFormat
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param format the pixel format to query
+ * \param format the pixel format to query.
  * \returns the human readable name of the specified pixel format or
  *          `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
  *
@@ -771,12 +771,12 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(SDL_PixelFormatEn
 /**
  * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
  *
- * \param format one of the SDL_PixelFormatEnum values
- * \param bpp a bits per pixel value; usually 15, 16, or 32
- * \param Rmask a pointer filled in with the red mask for the format
- * \param Gmask a pointer filled in with the green mask for the format
- * \param Bmask a pointer filled in with the blue mask for the format
- * \param Amask a pointer filled in with the alpha mask for the format
+ * \param format one of the SDL_PixelFormatEnum values.
+ * \param bpp a bits per pixel value; usually 15, 16, or 32.
+ * \param Rmask a pointer filled in with the red mask for the format.
+ * \param Gmask a pointer filled in with the green mask for the format.
+ * \param Bmask a pointer filled in with the blue mask for the format.
+ * \param Amask a pointer filled in with the alpha mask for the format.
  * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
  *          possible; call SDL_GetError() for more information.
  *
@@ -797,11 +797,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormatEnum(SDL_PixelFor
  * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
  * possible.
  *
- * \param bpp a bits per pixel value; usually 15, 16, or 32
- * \param Rmask the red mask for the format
- * \param Gmask the green mask for the format
- * \param Bmask the blue mask for the format
- * \param Amask the alpha mask for the format
+ * \param bpp a bits per pixel value; usually 15, 16, or 32.
+ * \param Rmask the red mask for the format.
+ * \param Gmask the green mask for the format.
+ * \param Bmask the blue mask for the format.
+ * \param Amask the alpha mask for the format.
  * \returns the SDL_PixelFormatEnum value corresponding to the format masks,
  *          or SDL_PIXELFORMAT_UNKNOWN if there isn't a match.
  *
@@ -822,7 +822,7 @@ extern SDL_DECLSPEC SDL_PixelFormatEnum SDLCALL SDL_GetPixelFormatEnumForMasks(i
  * allocated), and hence should not be modified, especially the palette. Weird
  * errors such as `Blit combination not supported` may occur.
  *
- * \param pixel_format one of the SDL_PixelFormatEnum values
+ * \param pixel_format one of the SDL_PixelFormatEnum values.
  * \returns the new SDL_PixelFormat structure or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -836,7 +836,7 @@ extern SDL_DECLSPEC SDL_PixelFormat * SDLCALL SDL_CreatePixelFormat(SDL_PixelFor
 /**
  * Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat().
  *
- * \param format the SDL_PixelFormat structure to free
+ * \param format the SDL_PixelFormat structure to free.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -849,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPixelFormat(SDL_PixelFormat *format)
  *
  * The palette entries are initialized to white.
  *
- * \param ncolors represents the number of color entries in the color palette
+ * \param ncolors represents the number of color entries in the color palette.
  * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
  *          there wasn't enough memory); call SDL_GetError() for more
  *          information.
@@ -865,8 +865,8 @@ extern SDL_DECLSPEC SDL_Palette *SDLCALL SDL_CreatePalette(int ncolors);
 /**
  * Set the palette for a pixel format structure.
  *
- * \param format the SDL_PixelFormat structure that will use the palette
- * \param palette the SDL_Palette structure that will be used
+ * \param format the SDL_PixelFormat structure that will use the palette.
+ * \param palette the SDL_Palette structure that will be used.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -878,10 +878,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * form
 /**
  * Set a range of colors in a palette.
  *
- * \param palette the SDL_Palette structure to modify
- * \param colors an array of SDL_Color structures to copy into the palette
- * \param firstcolor the index of the first palette entry to modify
- * \param ncolors the number of entries to modify
+ * \param palette the SDL_Palette structure to modify.
+ * \param colors an array of SDL_Color structures to copy into the palette.
+ * \param firstcolor the index of the first palette entry to modify.
+ * \param ncolors the number of entries to modify.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -894,7 +894,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
 /**
  * Free a palette created with SDL_CreatePalette().
  *
- * \param palette the SDL_Palette structure to be freed
+ * \param palette the SDL_Palette structure to be freed.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -920,11 +920,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette * palette);
  * format the return value can be assigned to a Uint16, and similarly a Uint8
  * for an 8-bpp format).
  *
- * \param format an SDL_PixelFormat structure describing the pixel format
- * \param r the red component of the pixel in the range 0-255
- * \param g the green component of the pixel in the range 0-255
- * \param b the blue component of the pixel in the range 0-255
- * \returns a pixel value
+ * \param format an SDL_PixelFormat structure describing the pixel format.
+ * \param r the red component of the pixel in the range 0-255.
+ * \param g the green component of the pixel in the range 0-255.
+ * \param b the blue component of the pixel in the range 0-255.
+ * \returns a pixel value.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -954,12 +954,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
  * for an 8-bpp format).
  *
  * \param format an SDL_PixelFormat structure describing the format of the
- *               pixel
- * \param r the red component of the pixel in the range 0-255
- * \param g the green component of the pixel in the range 0-255
- * \param b the blue component of the pixel in the range 0-255
- * \param a the alpha component of the pixel in the range 0-255
- * \returns a pixel value
+ *               pixel.
+ * \param r the red component of the pixel in the range 0-255.
+ * \param g the green component of the pixel in the range 0-255.
+ * \param b the blue component of the pixel in the range 0-255.
+ * \param a the alpha component of the pixel in the range 0-255.
+ * \returns a pixel value.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -979,12 +979,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
  * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
  *
- * \param pixel a pixel value
+ * \param pixel a pixel value.
  * \param format an SDL_PixelFormat structure describing the format of the
- *               pixel
- * \param r a pointer filled in with the red component
- * \param g a pointer filled in with the green component
- * \param b a pointer filled in with the blue component
+ *               pixel.
+ * \param r a pointer filled in with the red component.
+ * \param g a pointer filled in with the green component.
+ * \param b a pointer filled in with the blue component.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -1007,13 +1007,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
  * If the surface has no alpha component, the alpha will be returned as 0xff
  * (100% opaque).
  *
- * \param pixel a pixel value
+ * \param pixel a pixel value.
  * \param format an SDL_PixelFormat structure describing the format of the
- *               pixel
- * \param r a pointer filled in with the red component
- * \param g a pointer filled in with the green component
- * \param b a pointer filled in with the blue component
- * \param a a pointer filled in with the alpha component
+ *               pixel.
+ * \param r a pointer filled in with the red component.
+ * \param g a pointer filled in with the green component.
+ * \param b a pointer filled in with the blue component.
+ * \param a a pointer filled in with the alpha component.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_properties.h

@@ -97,8 +97,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
  * SDL_SetPropertyWithCleanup()), which will not be copied. Any property that
  * already exists on `dst` will be overwritten.
  *
- * \param src the properties to copy
- * \param dst the destination properties
+ * \param src the properties to copy.
+ * \param dst the destination properties.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -120,7 +120,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro
  * or want to guarantee that properties being queried aren't freed in another
  * thread.
  *
- * \param props the properties to lock
+ * \param props the properties to lock.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -135,7 +135,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
 /**
  * Unlock a set of properties.
  *
- * \param props the properties to unlock
+ * \param props the properties to unlock.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -181,12 +181,12 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value)
  * instead, as those functions will handle cleanup on your behalf. This
  * function is only for more complex, custom data.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property, or NULL to delete the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property, or NULL to delete the property.
  * \param cleanup the function to call when this property is deleted, or NULL
- *                if no cleanup is necessary
- * \param userdata a pointer that is passed to the cleanup function
+ *                if no cleanup is necessary.
+ * \param userdata a pointer that is passed to the cleanup function.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -203,9 +203,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID prop
 /**
  * Set a property on a set of properties.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property, or NULL to delete the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property, or NULL to delete the property.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -229,9 +229,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const ch
  * This function makes a copy of the string; the caller does not have to
  * preserve the data after this call completes.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property, or NULL to delete the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property, or NULL to delete the property.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -246,9 +246,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co
 /**
  * Set an integer property on a set of properties.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -263,9 +263,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co
 /**
  * Set a floating point property on a set of properties.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -280,9 +280,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con
 /**
  * Set a boolean property on a set of properties.
  *
- * \param props the properties to modify
- * \param name the name of the property to modify
- * \param value the new value of the property
+ * \param props the properties to modify.
+ * \param name the name of the property to modify.
+ * \param value the new value of the property.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -297,8 +297,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, c
 /**
  * Return whether a property exists in a set of properties.
  *
- * \param props the properties to query
- * \param name the name of the property to query
+ * \param props the properties to query.
+ * \param name the name of the property to query.
  * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -312,8 +312,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con
 /**
  * Get the type of a property on a set of properties.
  *
- * \param props the properties to query
- * \param name the name of the property to query
+ * \param props the properties to query.
+ * \param name the name of the property to query.
  * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
  *          not set.
  *
@@ -333,9 +333,9 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI
  * "SDL.internal.". These should be considered read-only and should not be
  * modified by applications.
  *
- * \param props the properties to query
- * \param name the name of the property to query
- * \param default_value the default value of the property
+ * \param props the properties to query.
+ * \param name the name of the property to query.
+ * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
  *          not a pointer property.
  *
@@ -362,9 +362,9 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param props the properties to query
- * \param name the name of the property to query
- * \param default_value the default value of the property
+ * \param props the properties to query.
+ * \param name the name of the property to query.
+ * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
  *          not a string property.
  *
@@ -384,9 +384,9 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID p
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a number property.
  *
- * \param props the properties to query
- * \param name the name of the property to query
- * \param default_value the default value of the property
+ * \param props the properties to query.
+ * \param name the name of the property to query.
+ * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
  *          not a number property.
  *
@@ -406,9 +406,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props,
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a floating point property.
  *
- * \param props the properties to query
- * \param name the name of the property to query
- * \param default_value the default value of the property
+ * \param props the properties to query.
+ * \param name the name of the property to query.
+ * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
  *          not a float property.
  *
@@ -428,9 +428,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a boolean property.
  *
- * \param props the properties to query
- * \param name the name of the property to query
- * \param default_value the default value of the property
+ * \param props the properties to query.
+ * \param name the name of the property to query.
+ * \param default_value the default value of the property.
  * \returns the value of the property, or `default_value` if it is not set or
  *          not a float property.
  *
@@ -447,8 +447,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID pro
 /**
  * Clear a property on a set of properties.
  *
- * \param props the properties to modify
- * \param name the name of the property to clear
+ * \param props the properties to modify.
+ * \param name the name of the property to clear.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -483,9 +483,9 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop
  * The callback function is called for each property on the set of properties.
  * The properties are locked during enumeration.
  *
- * \param props the properties to query
- * \param callback the function to call for each property
- * \param userdata a pointer that is passed to `callback`
+ * \param props the properties to query.
+ * \param callback the function to call for each property.
+ * \param userdata a pointer that is passed to `callback`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -501,7 +501,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props,
  * All properties are deleted and their cleanup functions will be called, if
  * any.
  *
- * \param props the properties to destroy
+ * \param props the properties to destroy.
  *
  * \threadsafety This function should not be called while these properties are
  *               locked or other threads might be setting or getting values

include/SDL3/SDL_rect.h

@@ -192,8 +192,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
  *
  * If either pointer is NULL the function will return SDL_FALSE.
  *
- * \param A an SDL_Rect structure representing the first rectangle
- * \param B an SDL_Rect structure representing the second rectangle
+ * \param A an SDL_Rect structure representing the first rectangle.
+ * \param B an SDL_Rect structure representing the second rectangle.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -210,10 +210,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A,
  *
  * If `result` is NULL then this function will return SDL_FALSE.
  *
- * \param A an SDL_Rect structure representing the first rectangle
- * \param B an SDL_Rect structure representing the second rectangle
+ * \param A an SDL_Rect structure representing the first rectangle.
+ * \param B an SDL_Rect structure representing the second rectangle.
  * \param result an SDL_Rect structure filled in with the intersection of
- *               rectangles `A` and `B`
+ *               rectangles `A` and `B`.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -227,10 +227,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A,
 /**
  * Calculate the union of two rectangles.
  *
- * \param A an SDL_Rect structure representing the first rectangle
- * \param B an SDL_Rect structure representing the second rectangle
+ * \param A an SDL_Rect structure representing the first rectangle.
+ * \param B an SDL_Rect structure representing the second rectangle.
  * \param result an SDL_Rect structure filled in with the union of rectangles
- *               `A` and `B`
+ *               `A` and `B`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -247,11 +247,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A,
  * considered.
  *
  * \param points an array of SDL_Point structures representing points to be
- *               enclosed
- * \param count the number of structures in the `points` array
- * \param clip an SDL_Rect used for clipping or NULL to enclose all points
+ *               enclosed.
+ * \param count the number of structures in the `points` array.
+ * \param clip an SDL_Rect used for clipping or NULL to enclose all points.
  * \param result an SDL_Rect structure filled in with the minimal enclosing
- *               rectangle
+ *               rectangle.
  * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
  *          points were outside of the clipping rectangle.
  *
@@ -271,11 +271,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point
  * both ends will be clipped to the boundary of the rectangle and the new
  * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
  *
- * \param rect an SDL_Rect structure representing the rectangle to intersect
- * \param X1 a pointer to the starting X-coordinate of the line
- * \param Y1 a pointer to the starting Y-coordinate of the line
- * \param X2 a pointer to the ending X-coordinate of the line
- * \param Y2 a pointer to the ending Y-coordinate of the line
+ * \param rect an SDL_Rect structure representing the rectangle to intersect.
+ * \param X1 a pointer to the starting X-coordinate of the line.
+ * \param Y1 a pointer to the starting Y-coordinate of the line.
+ * \param X2 a pointer to the ending X-coordinate of the line.
+ * \param Y2 a pointer to the ending Y-coordinate of the line.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -408,8 +408,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec
  *
  * If either pointer is NULL the function will return SDL_FALSE.
  *
- * \param A an SDL_FRect structure representing the first rectangle
- * \param B an SDL_FRect structure representing the second rectangle
+ * \param A an SDL_FRect structure representing the first rectangle.
+ * \param B an SDL_FRect structure representing the second rectangle.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -424,10 +424,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRec
  *
  * If `result` is NULL then this function will return SDL_FALSE.
  *
- * \param A an SDL_FRect structure representing the first rectangle
- * \param B an SDL_FRect structure representing the second rectangle
+ * \param A an SDL_FRect structure representing the first rectangle.
+ * \param B an SDL_FRect structure representing the second rectangle.
  * \param result an SDL_FRect structure filled in with the intersection of
- *               rectangles `A` and `B`
+ *               rectangles `A` and `B`.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -441,10 +441,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec
 /**
  * Calculate the union of two rectangles with float precision.
  *
- * \param A an SDL_FRect structure representing the first rectangle
- * \param B an SDL_FRect structure representing the second rectangle
+ * \param A an SDL_FRect structure representing the first rectangle.
+ * \param B an SDL_FRect structure representing the second rectangle.
  * \param result an SDL_FRect structure filled in with the union of rectangles
- *               `A` and `B`
+ *               `A` and `B`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -462,11 +462,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
  * considered.
  *
  * \param points an array of SDL_FPoint structures representing points to be
- *               enclosed
- * \param count the number of structures in the `points` array
- * \param clip an SDL_FRect used for clipping or NULL to enclose all points
+ *               enclosed.
+ * \param count the number of structures in the `points` array.
+ * \param clip an SDL_FRect used for clipping or NULL to enclose all points.
  * \param result an SDL_FRect structure filled in with the minimal enclosing
- *               rectangle
+ *               rectangle.
  * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
  *          points were outside of the clipping rectangle.
  *
@@ -487,11 +487,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F
  * both ends will be clipped to the boundary of the rectangle and the new
  * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
  *
- * \param rect an SDL_FRect structure representing the rectangle to intersect
- * \param X1 a pointer to the starting X-coordinate of the line
- * \param Y1 a pointer to the starting Y-coordinate of the line
- * \param X2 a pointer to the ending X-coordinate of the line
- * \param Y2 a pointer to the ending Y-coordinate of the line
+ * \param rect an SDL_FRect structure representing the rectangle to intersect.
+ * \param X1 a pointer to the starting X-coordinate of the line.
+ * \param Y1 a pointer to the starting Y-coordinate of the line.
+ * \param X2 a pointer to the ending X-coordinate of the line.
+ * \param Y2 a pointer to the ending Y-coordinate of the line.
  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.

include/SDL3/SDL_sensor.h

@@ -146,7 +146,7 @@ typedef enum SDL_SensorType
 /**
  * Get a list of currently connected sensors.
  *
- * \param count a pointer filled in with the number of sensors returned
+ * \param count a pointer filled in with the number of sensors returned.
  * \returns a 0 terminated array of sensor instance IDs which should be freed
  *          with SDL_free(), or NULL on error; call SDL_GetError() for more
  *          details.
@@ -160,8 +160,8 @@ extern SDL_DECLSPEC SDL_SensorID *SDLCALL SDL_GetSensors(int *count);
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param instance_id the sensor instance ID
- * \returns the sensor name, or NULL if `instance_id` is not valid
+ * \param instance_id the sensor instance ID.
+ * \returns the sensor name, or NULL if `instance_id` is not valid.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -170,9 +170,9 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID i
 /**
  * Get the type of a sensor.
  *
- * \param instance_id the sensor instance ID
+ * \param instance_id the sensor instance ID.
  * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is
- *          not valid
+ *          not valid.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -181,9 +181,9 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorI
 /**
  * Get the platform dependent type of a sensor.
  *
- * \param instance_id the sensor instance ID
+ * \param instance_id the sensor instance ID.
  * \returns the sensor platform dependent type, or -1 if `instance_id` is not
- *          valid
+ *          valid.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -192,7 +192,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorInstanceNonPortableType(SDL_SensorI
 /**
  * Open a sensor for use.
  *
- * \param instance_id the sensor instance ID
+ * \param instance_id the sensor instance ID.
  * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
  *
  * \since This function is available since SDL 3.0.0.
@@ -202,7 +202,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id)
 /**
  * Return the SDL_Sensor associated with an instance ID.
  *
- * \param instance_id the sensor instance ID
+ * \param instance_id the sensor instance ID.
  * \returns an SDL_Sensor object.
  *
  * \since This function is available since SDL 3.0.0.
@@ -212,7 +212,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID
 /**
  * Get the properties associated with a sensor.
  *
- * \param sensor The SDL_Sensor object
+ * \param sensor the SDL_Sensor object.
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -228,7 +228,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param sensor The SDL_Sensor object
+ * \param sensor the SDL_Sensor object.
  * \returns the sensor name, or NULL if `sensor` is NULL.
  *
  * \since This function is available since SDL 3.0.0.
@@ -238,7 +238,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetSensorName(SDL_Sensor *sensor);
 /**
  * Get the type of a sensor.
  *
- * \param sensor The SDL_Sensor object to inspect
+ * \param sensor the SDL_Sensor object to inspect.
  * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
  *          NULL.
  *
@@ -249,7 +249,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor)
 /**
  * Get the platform dependent type of a sensor.
  *
- * \param sensor The SDL_Sensor object to inspect
+ * \param sensor the SDL_Sensor object to inspect.
  * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
  *
  * \since This function is available since SDL 3.0.0.
@@ -259,7 +259,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
 /**
  * Get the instance ID of a sensor.
  *
- * \param sensor The SDL_Sensor object to inspect
+ * \param sensor the SDL_Sensor object to inspect.
  * \returns the sensor instance ID, or 0 if `sensor` is NULL.
  *
  * \since This function is available since SDL 3.0.0.
@@ -271,9 +271,9 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorInstanceID(SDL_Sensor *sen
  *
  * The number of values and interpretation of the data is sensor dependent.
  *
- * \param sensor The SDL_Sensor object to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ * \param sensor the SDL_Sensor object to query.
+ * \param data a pointer filled with the current sensor state.
+ * \param num_values the number of values to write to data.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -284,7 +284,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *dat
 /**
  * Close a sensor previously opened with SDL_OpenSensor().
  *
- * \param sensor The SDL_Sensor object to close
+ * \param sensor the SDL_Sensor object to close.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_stdinc.h

@@ -509,10 +509,10 @@ typedef void (SDLCALL *SDL_free_func)(void *mem);
  * runtime's `malloc` functions behind the scenes! Different platforms and
  * build configurations might do any number of unexpected things.
  *
- * \param malloc_func filled with malloc function
- * \param calloc_func filled with calloc function
- * \param realloc_func filled with realloc function
- * \param free_func filled with free function
+ * \param malloc_func filled with malloc function.
+ * \param calloc_func filled with calloc function.
+ * \param realloc_func filled with realloc function.
+ * \param free_func filled with free function.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -526,10 +526,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func
 /**
  * Get the current set of SDL memory functions.
  *
- * \param malloc_func filled with malloc function
- * \param calloc_func filled with calloc function
- * \param realloc_func filled with realloc function
- * \param free_func filled with free function
+ * \param malloc_func filled with malloc function.
+ * \param calloc_func filled with calloc function.
+ * \param realloc_func filled with realloc function.
+ * \param free_func filled with free function.
  *
  * \threadsafety This does not hold a lock, so do not call this in the
  *               unlikely event of a background thread calling
@@ -555,10 +555,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_
  * If used, usually this needs to be the first call made into the SDL library,
  * if not the very first thing done at program startup time.
  *
- * \param malloc_func custom malloc function
- * \param calloc_func custom calloc function
- * \param realloc_func custom realloc function
- * \param free_func custom free function
+ * \param malloc_func custom malloc function.
+ * \param calloc_func custom calloc function.
+ * \param realloc_func custom realloc function.
+ * \param free_func custom free function.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -588,9 +588,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_fu
  * The memory returned by this function must be freed with SDL_aligned_free(),
  * and _not_ SDL_free.
  *
- * \param alignment the alignment requested
- * \param size the size to allocate
- * \returns a pointer to the aligned memory
+ * \param alignment the alignment requested.
+ * \param size the size to allocate.
+ * \returns a pointer to the aligned memory.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -619,7 +619,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem);
 /**
  * Get the number of outstanding (unfreed) allocations.
  *
- * \returns the number of allocations
+ * \returns the number of allocations.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -940,8 +940,8 @@ extern SDL_DECLSPEC wchar_t *SDLCALL SDL_wcsnstr(const wchar_t *haystack, const
  * character; it does not care if the string is well-formed UTF-16 (or UTF-32,
  * depending on your platform's wchar_t size), or uses valid Unicode values.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -970,9 +970,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s
  * null-terminator character before this count), they will be considered
  * equal.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
- * \param maxlen The maximum number of wchar_t to compare.
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
+ * \param maxlen the maximum number of wchar_t to compare.
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1001,8 +1001,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *
  * CHARACTER), which is to say two strings of random bits may turn out to
  * match if they convert to the same amount of replacement characters.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1042,9 +1042,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_
  * null-terminator character before this number of bytes), they will be
  * considered equal.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
- * \param maxlen The maximum number of wchar_t values to compare.
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
+ * \param maxlen the maximum number of wchar_t values to compare.
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1076,7 +1076,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strrev(char *str);
  * malformed UTF-8!--and converts ASCII characters 'a' through 'z' to their
  * uppercase equivalents in-place, returning the original `str` pointer.
  *
- * \param str The string to convert in-place. Can not be NULL.
+ * \param str the string to convert in-place. Can not be NULL.
  * \returns the `str` pointer passed into this function.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -1097,7 +1097,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strupr(char *str);
  * malformed UTF-8!--and converts ASCII characters 'A' through 'Z' to their
  * lowercase equivalents in-place, returning the original `str` pointer.
  *
- * \param str The string to convert in-place. Can not be NULL.
+ * \param str the string to convert in-place. Can not be NULL.
  * \returns the `str` pointer passed into this function.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -1140,8 +1140,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp);
  * null-terminating character. Also due to the nature of UTF-8, this can be
  * used with SDL_qsort() to put strings in (roughly) alphabetical order.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1169,9 +1169,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2);
  * match to this number of bytes (or both have matched to a null-terminator
  * character before this number of bytes), they will be considered equal.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
- * \param maxlen The maximum number of _bytes_ to compare.
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
+ * \param maxlen the maximum number of _bytes_ to compare.
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1198,8 +1198,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2,
  * CHARACTER), which is to say two strings of random bits may turn out to
  * match if they convert to the same amount of replacement characters.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1237,9 +1237,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str
  * match to this number of bytes (or both have matched to a null-terminator
  * character before this number of bytes), they will be considered equal.
  *
- * \param str1 The first string to compare. NULL is not permitted!
- * \param str2 The second string to compare. NULL is not permitted!
- * \param maxlen The maximum number of bytes to compare.
+ * \param str1 the first string to compare. NULL is not permitted!
+ * \param str2 the second string to compare. NULL is not permitted!
+ * \param maxlen the maximum number of bytes to compare.
  * \returns less than zero if str1 is "less than" str2, greater than zero if
  *          str1 is "greater than" str2, and zero if the strings match
  *          exactly.
@@ -1283,8 +1283,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value
- * \returns arc cosine of `x`, in radians
+ * \param x floating point value.
+ * \returns arc cosine of `x`, in radians.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1314,7 +1314,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x);
  * updated.
  *
  * \param x floating point value.
- * \returns arc cosine of `x`, in radians
+ * \returns arc cosine of `x`, in radians.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1438,7 +1438,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x);
  * updated.
  *
  * \param x floating point value.
- * \returns arc tangent of of `x` in radians, or 0 if `x = 0`
+ * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1471,7 +1471,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param y floating point value of the numerator (y coordinate)
+ * \param y floating point value of the numerator (y coordinate).
  * \param x floating point value of the denominator (x coordinate).
  * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
  *          `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
@@ -1507,7 +1507,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param y floating point value of the numerator (y coordinate)
+ * \param y floating point value of the numerator (y coordinate).
  * \param x floating point value of the denominator (x coordinate).
  * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
  *          `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
@@ -1535,8 +1535,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
  * This function operates on double-precision floating point values, use
  * SDL_ceilf for single-precision floats.
  *
- * \param x floating point value
- * \returns the ceiling of `x`
+ * \param x floating point value.
+ * \returns the ceiling of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1563,8 +1563,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x);
  * This function operates on single-precision floating point values, use
  * SDL_ceil for double-precision floats.
  *
- * \param x floating point value
- * \returns the ceiling of `x`
+ * \param x floating point value.
+ * \returns the ceiling of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1590,9 +1590,10 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_copysignf for single-precision floats.
  *
- * \param x floating point value to use as the magnitude
- * \param y floating point value to use as the sign
- * \returns the floating point value with the sign of y and the magnitude of x
+ * \param x floating point value to use as the magnitude.
+ * \param y floating point value to use as the sign.
+ * \returns the floating point value with the sign of y and the magnitude of
+ *          x.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1615,9 +1616,10 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y);
  * This function operates on single-precision floating point values, use
  * SDL_copysign for double-precision floats.
  *
- * \param x floating point value to use as the magnitude
- * \param y floating point value to use as the sign
- * \returns the floating point value with the sign of y and the magnitude of x
+ * \param x floating point value to use as the magnitude.
+ * \param y floating point value to use as the sign.
+ * \returns the floating point value with the sign of y and the magnitude of
+ *          x.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1643,8 +1645,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns cosine of `x`
+ * \param x floating point value, in radians.
+ * \returns cosine of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1671,8 +1673,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns cosine of `x`
+ * \param x floating point value, in radians.
+ * \returns cosine of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1704,8 +1706,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value
- * \returns value of `e^x`
+ * \param x floating point value.
+ * \returns value of `e^x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1736,8 +1738,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value
- * \returns value of `e^x`
+ * \param x floating point value.
+ * \returns value of `e^x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1758,8 +1760,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_copysignf for single-precision floats.
  *
- * \param x floating point value to use as the magnitude
- * \returns the absolute value of `x`
+ * \param x floating point value to use as the magnitude.
+ * \returns the absolute value of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1779,8 +1781,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x);
  * This function operates on single-precision floating point values, use
  * SDL_copysignf for double-precision floats.
  *
- * \param x floating point value to use as the magnitude
- * \returns the absolute value of `x`
+ * \param x floating point value to use as the magnitude.
+ * \returns the absolute value of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1803,8 +1805,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_floorf for single-precision floats.
  *
- * \param x floating point value
- * \returns the floor of `x`
+ * \param x floating point value.
+ * \returns the floor of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1831,8 +1833,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x);
  * This function operates on single-precision floating point values, use
  * SDL_floorf for double-precision floats.
  *
- * \param x floating point value
- * \returns the floor of `x`
+ * \param x floating point value.
+ * \returns the floor of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1859,8 +1861,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_truncf for single-precision floats.
  *
- * \param x floating point value
- * \returns `x` truncated to an integer
+ * \param x floating point value.
+ * \returns `x` truncated to an integer.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1888,8 +1890,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x);
  * This function operates on single-precision floating point values, use
  * SDL_truncf for double-precision floats.
  *
- * \param x floating point value
- * \returns `x` truncated to an integer
+ * \param x floating point value.
+ * \returns `x` truncated to an integer.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1916,9 +1918,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_fmodf for single-precision floats.
  *
- * \param x the numerator
+ * \param x the numerator.
  * \param y the denominator. Must not be 0.
- * \returns the remainder of `x / y`
+ * \returns the remainder of `x / y`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1946,9 +1948,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y);
  * This function operates on single-precision floating point values, use
  * SDL_fmod for single-precision floats.
  *
- * \param x the numerator
+ * \param x the numerator.
  * \param y the denominator. Must not be 0.
- * \returns the remainder of `x / y`
+ * \returns the remainder of `x / y`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -1982,7 +1984,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
  * updated.
  *
  * \param x floating point value. Must be greater than 0.
- * \returns the natural logarithm of `x`
+ * \returns the natural logarithm of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2012,7 +2014,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x);
  * updated.
  *
  * \param x floating point value. Must be greater than 0.
- * \returns the natural logarithm of `x`
+ * \returns the natural logarithm of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2041,7 +2043,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x);
  * updated.
  *
  * \param x floating point value. Must be greater than 0.
- * \returns the logarithm of `x`
+ * \returns the logarithm of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2071,7 +2073,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x);
  * updated.
  *
  * \param x floating point value. Must be greater than 0.
- * \returns the logarithm of `x`
+ * \returns the logarithm of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2089,9 +2091,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x);
  * This function operates on double-precision floating point values, use
  * SDL_modff for single-precision floats.
  *
- * \param x floating point value
- * \param y output pointer to store the integer part of `x`
- * \returns the fractional part of `x`
+ * \param x floating point value.
+ * \param y output pointer to store the integer part of `x`.
+ * \returns the fractional part of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2109,9 +2111,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y);
  * This function operates on single-precision floating point values, use
  * SDL_modf for double-precision floats.
  *
- * \param x floating point value
- * \param y output pointer to store the integer part of `x`
- * \returns the fractional part of `x`
+ * \param x floating point value.
+ * \param y output pointer to store the integer part of `x`.
+ * \returns the fractional part of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2141,9 +2143,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x the base
- * \param y the exponent
- * \returns `x` raised to the power `y`
+ * \param x the base.
+ * \param y the exponent.
+ * \returns `x` raised to the power `y`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2173,9 +2175,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x the base
- * \param y the exponent
- * \returns `x` raised to the power `y`
+ * \param x the base.
+ * \param y the exponent.
+ * \returns `x` raised to the power `y`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2201,8 +2203,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y);
  * SDL_roundf for single-precision floats. To get the result as an integer
  * type, use SDL_lround.
  *
- * \param x floating point value
- * \returns the nearest integer to `x`
+ * \param x floating point value.
+ * \returns the nearest integer to `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2230,8 +2232,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x);
  * SDL_roundf for single-precision floats. To get the result as an integer
  * type, use SDL_lroundf.
  *
- * \param x floating point value
- * \returns the nearest integer to `x`
+ * \param x floating point value.
+ * \returns the nearest integer to `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2259,8 +2261,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x);
  * SDL_lround for single-precision floats. To get the result as a
  * floating-point type, use SDL_round.
  *
- * \param x floating point value
- * \returns the nearest integer to `x`
+ * \param x floating point value.
+ * \returns the nearest integer to `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2288,8 +2290,8 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x);
  * SDL_lroundf for double-precision floats. To get the result as a
  * floating-point type, use SDL_roundf,
  *
- * \param x floating point value
- * \returns the nearest integer to `x`
+ * \param x floating point value.
+ * \returns the nearest integer to `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2315,9 +2317,9 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x);
  * This function operates on double-precision floating point values, use
  * SDL_scalbnf for single-precision floats.
  *
- * \param x floating point value to be scaled
- * \param n integer exponent
- * \returns `x * 2^n`
+ * \param x floating point value to be scaled.
+ * \param n integer exponent.
+ * \returns `x * 2^n`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2340,9 +2342,9 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
  * This function operates on single-precision floating point values, use
  * SDL_scalbn for double-precision floats.
  *
- * \param x floating point value to be scaled
- * \param n integer exponent
- * \returns `x * 2^n`
+ * \param x floating point value to be scaled.
+ * \param n integer exponent.
+ * \returns `x * 2^n`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2368,8 +2370,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns sine of `x`
+ * \param x floating point value, in radians.
+ * \returns sine of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2396,8 +2398,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns sine of `x`
+ * \param x floating point value, in radians.
+ * \returns sine of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2425,7 +2427,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x);
  * updated.
  *
  * \param x floating point value. Must be greater than or equal to 0.
- * \returns square root of `x`
+ * \returns square root of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2451,7 +2453,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x);
  * updated.
  *
  * \param x floating point value. Must be greater than or equal to 0.
- * \returns square root of `x`
+ * \returns square root of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2476,8 +2478,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns tangent of `x`
+ * \param x floating point value, in radians.
+ * \returns tangent of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2506,8 +2508,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x);
  * the same input on different machines or operating systems, or if SDL is
  * updated.
  *
- * \param x floating point value, in radians
- * \returns tangent of `x`
+ * \param x floating point value, in radians.
+ * \returns tangent of `x`.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -2641,8 +2643,8 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size);
  *
  * Otherwise store `a * b` via ret and return 0.
  *
- * \param a the multiplicand
- * \param b the multiplier
+ * \param a the multiplicand.
+ * \param b the multiplier.
  * \param ret on non-overflow output, stores the multiplication result. May
  *            not be NULL.
  * \returns -1 on overflow, 0 if result doesn't overflow.

include/SDL3/SDL_storage.h

@@ -101,8 +101,8 @@ typedef struct SDL_Storage SDL_Storage;
 /**
  * Opens up a read-only container for the application's filesystem.
  *
- * \param override a path to override the backend's default title root
- * \param props a property list that may contain backend-specific information
+ * \param override a path to override the backend's default title root.
+ * \param props a property list that may contain backend-specific information.
  * \returns a title storage container on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -123,9 +123,9 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenTitleStorage(const char *overri
  * This allows the backend to properly batch file operations and flush them
  * when the container has been closed; ensuring safe and optimal save I/O.
  *
- * \param org the name of your organization
- * \param app the name of your application
- * \param props a property list that may contain backend-specific information
+ * \param org the name of your organization.
+ * \param app the name of your application.
+ * \param props a property list that may contain backend-specific information.
  * \returns a user storage container on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -149,7 +149,7 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenUserStorage(const char *org, co
  * SDL_OpenUserStorage() for access to user data.
  *
  * \param path the base path prepended to all storage paths, or NULL for no
- *             base path
+ *             base path.
  * \returns a filesystem storage container on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -173,8 +173,8 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenFileStorage(const char *path);
  * should use the built-in implementations in SDL, like SDL_OpenTitleStorage()
  * or SDL_OpenUserStorage().
  *
- * \param iface the function table to be used by this container
- * \param userdata the pointer that will be passed to the store interface
+ * \param iface the function table to be used by this container.
+ * \param userdata the pointer that will be passed to the store interface.
  * \returns a storage container on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -192,7 +192,7 @@ extern SDL_DECLSPEC SDL_Storage *SDLCALL SDL_OpenStorage(const SDL_StorageInterf
 /**
  * Closes and frees a storage container.
  *
- * \param storage a storage container to close
+ * \param storage a storage container to close.
  * \returns 0 if the container was freed with no errors, a negative value
  *          otherwise; call SDL_GetError() for more information. Even if the
  *          function returns an error, the container data will be freed; the
@@ -214,8 +214,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_CloseStorage(SDL_Storage *storage);
  * SDL_TRUE - however, it is not recommended to spinwait on this call, as the
  * backend may depend on a synchronous message loop.
  *
- * \param storage a storage container to query
- * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise
+ * \param storage a storage container to query.
+ * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -224,9 +224,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
 /**
  * Query the size of a file within a storage container.
  *
- * \param storage a storage container to query
- * \param path the relative path of the file to query
- * \param length a pointer to be filled with the file's length
+ * \param storage a storage container to query.
+ * \param path the relative path of the file to query.
+ * \param length a pointer to be filled with the file's length.
  * \returns 0 if the file could be queried, a negative value otherwise; call
  *          SDL_GetError() for more information.
  *
@@ -241,10 +241,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con
  * Synchronously read a file from a storage container into a client-provided
  * buffer.
  *
- * \param storage a storage container to read from
- * \param path the relative path of the file to read
- * \param destination a client-provided buffer to read the file into
- * \param length the length of the destination buffer
+ * \param storage a storage container to read from.
+ * \param path the relative path of the file to read.
+ * \param destination a client-provided buffer to read the file into.
+ * \param length the length of the destination buffer.
  * \returns 0 if the file was read, a negative value otherwise; call
  *          SDL_GetError() for more information.
  *
@@ -259,10 +259,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
 /**
  * Synchronously write a file from client memory into a storage container.
  *
- * \param storage a storage container to write to
- * \param path the relative path of the file to write
- * \param source a client-provided buffer to write from
- * \param length the length of the source buffer
+ * \param storage a storage container to write to.
+ * \param path the relative path of the file to write.
+ * \param source a client-provided buffer to write from.
+ * \param length the length of the source buffer.
  * \returns 0 if the file was written, a negative value otherwise; call
  *          SDL_GetError() for more information.
  *
@@ -277,8 +277,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const
 /**
  * Create a directory in a writable storage container.
  *
- * \param storage a storage container
- * \param path the path of the directory to create
+ * \param storage a storage container.
+ * \param path the path of the directory to create.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -295,10 +295,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage,
  * callback, called once for each directory entry, until all results have been
  * provided or the callback returns <= 0.
  *
- * \param storage a storage container
- * \param path the path of the directory to enumerate
- * \param callback a function that is called for each entry in the directory
- * \param userdata a pointer that is passed to `callback`
+ * \param storage a storage container.
+ * \param path the path of the directory to enumerate.
+ * \param callback a function that is called for each entry in the directory.
+ * \param userdata a pointer that is passed to `callback`.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -311,8 +311,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *stora
 /**
  * Remove a file or an empty directory in a writable storage container.
  *
- * \param storage a storage container
- * \param path the path of the directory to enumerate
+ * \param storage a storage container.
+ * \param path the path of the directory to enumerate.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -325,9 +325,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, cons
 /**
  * Rename a file or directory in a writable storage container.
  *
- * \param storage a storage container
- * \param oldpath the old path
- * \param newpath the new path
+ * \param storage a storage container.
+ * \param oldpath the old path.
+ * \param newpath the new path.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -340,10 +340,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, cons
 /**
  * Get information about a filesystem path in a storage container.
  *
- * \param storage a storage container
- * \param path the path to query
+ * \param storage a storage container.
+ * \param path the path to query.
  * \param info a pointer filled in with information about the path, or NULL to
- *             check for the existence of a file
+ *             check for the existence of a file.
  * \returns 0 on success or a negative error code if the file doesn't exist,
  *          or another failure; call SDL_GetError() for more information.
  *
@@ -356,8 +356,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, con
 /**
  * Queries the remaining space in a storage container.
  *
- * \param storage a storage container to query
- * \returns the amount of remaining space, in bytes
+ * \param storage a storage container to query.
+ * \returns the amount of remaining space, in bytes.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -385,8 +385,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
  *
  * You must free the returned pointer with SDL_free() when done with it.
  *
- * \param storage a storage container
- * \param path the path of the directory to enumerate
+ * \param storage a storage container.
+ * \param path the path of the directory to enumerate.
  * \param pattern the pattern that files in the directory must match. Can be
  *                NULL.
  * \param flags `SDL_GLOB_*` bitflags that affect this search.

include/SDL3/SDL_surface.h

@@ -145,8 +145,8 @@ typedef struct SDL_Surface
 /**
  * Allocate a new RGB surface with a specific pixel format.
  *
- * \param width the width of the surface
- * \param height the height of the surface
+ * \param width the width of the surface.
+ * \param height the height of the surface.
  * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
  * \returns the new SDL_Surface structure that is created or NULL if it fails;
  *          call SDL_GetError() for more information.
@@ -171,10 +171,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
  * You may pass NULL for pixels and 0 for pitch to create a surface that you
  * will fill in with valid values later.
  *
- * \param pixels a pointer to existing pixel data
- * \param width the width of the surface
- * \param height the height of the surface
- * \param pitch the number of bytes between each row, including padding
+ * \param pixels a pointer to existing pixel data.
+ * \param width the width of the surface.
+ * \param height the height of the surface.
+ * \param pitch the number of bytes between each row, including padding.
  * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
  * \returns the new SDL_Surface structure that is created or NULL if it fails;
  *          call SDL_GetError() for more information.
@@ -225,7 +225,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface);
  *   where N is a floating point scale factor applied in linear space, and
  *   "none", which disables tone mapping. This defaults to "chrome".
  *
- * \param surface the SDL_Surface structure to query
+ * \param surface the SDL_Surface structure to query.
  * \returns a valid property ID on success or 0 on failure; call
  *          SDL_GetError() for more information.
  *
@@ -247,8 +247,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac
  * Setting the colorspace doesn't change the pixels, only how they are
  * interpreted in color operations.
  *
- * \param surface the SDL_Surface structure to update
- * \param colorspace an SDL_ColorSpace value describing the surface colorspace
+ * \param surface the SDL_Surface structure to update.
+ * \param colorspace an SDL_ColorSpace value describing the surface
+ *                   colorspace.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -263,9 +264,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, S
  * formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for
  * other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures.
  *
- * \param surface the SDL_Surface structure to query
+ * \param surface the SDL_Surface structure to query.
  * \param colorspace a pointer filled in with an SDL_ColorSpace value
- *                   describing the surface colorspace
+ *                   describing the surface colorspace.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -278,8 +279,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface, S
  *
  * A single palette can be shared with many surfaces.
  *
- * \param surface the SDL_Surface structure to update
- * \param palette the SDL_Palette structure to use
+ * \param surface the SDL_Surface structure to update.
+ * \param palette the SDL_Palette structure to use.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -299,7 +300,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_
  * 0, then you can read and write to the surface at any time, and the pixel
  * format of the surface will not change.
  *
- * \param surface the SDL_Surface structure to be locked
+ * \param surface the SDL_Surface structure to be locked.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -313,7 +314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
 /**
  * Release a surface after directly accessing the pixels.
  *
- * \param surface the SDL_Surface structure to be unlocked
+ * \param surface the SDL_Surface structure to be unlocked.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -327,9 +328,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
  * The new surface should be freed with SDL_DestroySurface(). Not doing so
  * will result in a memory leak.
  *
- * \param src the data stream for the surface
+ * \param src the data stream for the surface.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
- *                even in the case of an error
+ *                even in the case of an error.
  * \returns a pointer to a new SDL_Surface structure or NULL if there was an
  *          error; call SDL_GetError() for more information.
  *
@@ -347,7 +348,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_b
  * The new surface should be freed with SDL_DestroySurface(). Not doing so
  * will result in a memory leak.
  *
- * \param file the BMP file to load
+ * \param file the BMP file to load.
  * \returns a pointer to a new SDL_Surface structure or NULL if there was an
  *          error; call SDL_GetError() for more information.
  *
@@ -368,10 +369,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP(const char *file);
  * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
  * not supported.
  *
- * \param surface the SDL_Surface structure containing the image to be saved
- * \param dst a data stream to save to
+ * \param surface the SDL_Surface structure containing the image to be saved.
+ * \param dst a data stream to save to.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning,
- *                even in the case of an error
+ *                even in the case of an error.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -391,8 +392,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStrea
  * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
  * not supported.
  *
- * \param surface the SDL_Surface structure containing the image to be saved
- * \param file a file to save to
+ * \param surface the SDL_Surface structure containing the image to be saved.
+ * \param file a file to save to.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -409,8 +410,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi
  * If RLE is enabled, color key and alpha blending blits are much faster, but
  * the surface must be locked before directly accessing the pixels.
  *
- * \param surface the SDL_Surface structure to optimize
- * \param flag 0 to disable, non-zero to enable RLE acceleration
+ * \param surface the SDL_Surface structure to optimize.
+ * \param flag 0 to disable, non-zero to enable RLE acceleration.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -427,7 +428,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, int flag
  *
  * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
  *
- * \param surface the SDL_Surface structure to query
+ * \param surface the SDL_Surface structure to query.
  * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -449,9 +450,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
  * RLE acceleration can substantially speed up blitting of images with large
  * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
  *
- * \param surface the SDL_Surface structure to update
- * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
- * \param key the transparent pixel
+ * \param surface the SDL_Surface structure to update.
+ * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key.
+ * \param key the transparent pixel.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -467,7 +468,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, int
  *
  * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
  *
- * \param surface the SDL_Surface structure to query
+ * \param surface the SDL_Surface structure to query.
  * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.0.0.
@@ -485,8 +486,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface
  *
  * If the surface doesn't have color key enabled this function returns -1.
  *
- * \param surface the SDL_Surface structure to query
- * \param key a pointer filled in with the transparent pixel
+ * \param surface the SDL_Surface structure to query.
+ * \param key a pointer filled in with the transparent pixel.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -506,10 +507,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uin
  *
  * `srcC = srcC * (color / 255)`
  *
- * \param surface the SDL_Surface structure to update
- * \param r the red color value multiplied into blit operations
- * \param g the green color value multiplied into blit operations
- * \param b the blue color value multiplied into blit operations
+ * \param surface the SDL_Surface structure to update.
+ * \param r the red color value multiplied into blit operations.
+ * \param g the green color value multiplied into blit operations.
+ * \param b the blue color value multiplied into blit operations.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -524,10 +525,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uin
 /**
  * Get the additional color value multiplied into blit operations.
  *
- * \param surface the SDL_Surface structure to query
- * \param r a pointer filled in with the current red color value
- * \param g a pointer filled in with the current green color value
- * \param b a pointer filled in with the current blue color value
+ * \param surface the SDL_Surface structure to query.
+ * \param r a pointer filled in with the current red color value.
+ * \param g a pointer filled in with the current green color value.
+ * \param b a pointer filled in with the current blue color value.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -546,8 +547,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uin
  *
  * `srcA = srcA * (alpha / 255)`
  *
- * \param surface the SDL_Surface structure to update
- * \param alpha the alpha value multiplied into blit operations
+ * \param surface the SDL_Surface structure to update.
+ * \param alpha the alpha value multiplied into blit operations.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -561,8 +562,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uin
 /**
  * Get the additional alpha value used in blit operations.
  *
- * \param surface the SDL_Surface structure to query
- * \param alpha a pointer filled in with the current alpha value
+ * \param surface the SDL_Surface structure to query.
+ * \param alpha a pointer filled in with the current alpha value.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -580,8 +581,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uin
  * existing data, the blendmode of the SOURCE surface should be set to
  * `SDL_BLENDMODE_NONE`.
  *
- * \param surface the SDL_Surface structure to update
- * \param blendMode the SDL_BlendMode to use for blit blending
+ * \param surface the SDL_Surface structure to update.
+ * \param blendMode the SDL_BlendMode to use for blit blending.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -594,8 +595,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SD
 /**
  * Get the blend mode used for blit operations.
  *
- * \param surface the SDL_Surface structure to query
- * \param blendMode a pointer filled in with the current SDL_BlendMode
+ * \param surface the SDL_Surface structure to query.
+ * \param blendMode a pointer filled in with the current SDL_BlendMode.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -614,9 +615,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SD
  * Note that blits are automatically clipped to the edges of the source and
  * destination surfaces.
  *
- * \param surface the SDL_Surface structure to be clipped
+ * \param surface the SDL_Surface structure to be clipped.
  * \param rect the SDL_Rect structure representing the clipping rectangle, or
- *             NULL to disable clipping
+ *             NULL to disable clipping.
  * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
  *          SDL_FALSE and blits will be completely clipped.
  *
@@ -633,9 +634,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface
  * rectangle is drawn into.
  *
  * \param surface the SDL_Surface structure representing the surface to be
- *                clipped
+ *                clipped.
  * \param rect an SDL_Rect structure filled in with the clipping rectangle for
- *             the surface
+ *             the surface.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -648,8 +649,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL
 /**
  * Flip a surface vertically or horizontally.
  *
- * \param surface the surface to flip
- * \param flip the direction to flip
+ * \param surface the surface to flip.
+ * \param flip the direction to flip.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -680,9 +681,9 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surfa
  * surface. The new, optimized surface can then be used as the source for
  * future blits, making them faster.
  *
- * \param surface the existing SDL_Surface structure to convert
+ * \param surface the existing SDL_Surface structure to convert.
  * \param format the SDL_PixelFormat structure that the new surface is
- *               optimized for
+ *               optimized for.
  * \returns the new SDL_Surface structure that is created or NULL if it fails;
  *          call SDL_GetError() for more information.
  *
@@ -703,8 +704,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface
  * it might be easier to call but it doesn't have access to palette
  * information for the destination surface, in case that would be important.
  *
- * \param surface the existing SDL_Surface structure to convert
- * \param pixel_format the new pixel format
+ * \param surface the existing SDL_Surface structure to convert.
+ * \param pixel_format the new pixel format.
  * \returns the new SDL_Surface structure that is created or NULL if it fails;
  *          call SDL_GetError() for more information.
  *
@@ -724,10 +725,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *s
  * and returns the new surface. This will perform any pixel format and
  * colorspace conversion needed.
  *
- * \param surface the existing SDL_Surface structure to convert
- * \param pixel_format the new pixel format
- * \param colorspace the new colorspace
- * \param props an SDL_PropertiesID with additional color properties, or 0
+ * \param surface the existing SDL_Surface structure to convert.
+ * \param pixel_format the new pixel format.
+ * \param colorspace the new colorspace.
+ * \param props an SDL_PropertiesID with additional color properties, or 0.
  * \returns the new SDL_Surface structure that is created or NULL if it fails;
  *          call SDL_GetError() for more information.
  *
@@ -742,14 +743,14 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormatAndColorspace(S
 /**
  * Copy a block of pixels of one format to another format.
  *
- * \param width the width of the block to copy, in pixels
- * \param height the height of the block to copy, in pixels
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
- * \param src a pointer to the source pixels
- * \param src_pitch the pitch of the source pixels, in bytes
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
- * \param dst a pointer to be filled in with new pixel data
- * \param dst_pitch the pitch of the destination pixels, in bytes
+ * \param width the width of the block to copy, in pixels.
+ * \param height the height of the block to copy, in pixels.
+ * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
+ * \param src a pointer to the source pixels.
+ * \param src_pitch the pitch of the source pixels, in bytes.
+ * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
+ * \param dst a pointer to be filled in with new pixel data.
+ * \param dst_pitch the pitch of the destination pixels, in bytes.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -763,22 +764,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pix
  * Copy a block of pixels of one format and colorspace to another format and
  * colorspace.
  *
- * \param width the width of the block to copy, in pixels
- * \param height the height of the block to copy, in pixels
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
+ * \param width the width of the block to copy, in pixels.
+ * \param height the height of the block to copy, in pixels.
+ * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
  * \param src_colorspace an SDL_ColorSpace value describing the colorspace of
- *                       the `src` pixels
+ *                       the `src` pixels.
  * \param src_properties an SDL_PropertiesID with additional source color
- *                       properties, or 0
- * \param src a pointer to the source pixels
- * \param src_pitch the pitch of the source pixels, in bytes
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
+ *                       properties, or 0.
+ * \param src a pointer to the source pixels.
+ * \param src_pitch the pitch of the source pixels, in bytes.
+ * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
  * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of
- *                       the `dst` pixels
+ *                       the `dst` pixels.
  * \param dst_properties an SDL_PropertiesID with additional destination color
- *                       properties, or 0
- * \param dst a pointer to be filled in with new pixel data
- * \param dst_pitch the pitch of the destination pixels, in bytes
+ *                       properties, or 0.
+ * \param dst a pointer to be filled in with new pixel data.
+ * \param dst_pitch the pitch of the destination pixels, in bytes.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -795,14 +796,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int he
  *
  * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888.
  *
- * \param width the width of the block to convert, in pixels
- * \param height the height of the block to convert, in pixels
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
- * \param src a pointer to the source pixels
- * \param src_pitch the pitch of the source pixels, in bytes
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
- * \param dst a pointer to be filled in with premultiplied pixel data
- * \param dst_pitch the pitch of the destination pixels, in bytes
+ * \param width the width of the block to convert, in pixels.
+ * \param height the height of the block to convert, in pixels.
+ * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
+ * \param src a pointer to the source pixels.
+ * \param src_pitch the pitch of the source pixels, in bytes.
+ * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
+ * \param dst a pointer to be filled in with premultiplied pixel data.
+ * \param dst_pitch the pitch of the destination pixels, in bytes.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -822,10 +823,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_
  * SDL_SetSurfaceClipRect()), then this function will fill based on the
  * intersection of the clip rectangle and `rect`.
  *
- * \param dst the SDL_Surface structure that is the drawing target
+ * \param dst the SDL_Surface structure that is the drawing target.
  * \param rect the SDL_Rect structure representing the rectangle to fill, or
- *             NULL to fill the entire surface
- * \param color the color to fill with
+ *             NULL to fill the entire surface.
+ * \param color the color to fill with.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -847,10 +848,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_
  * SDL_SetSurfaceClipRect()), then this function will fill based on the
  * intersection of the clip rectangle and `rect`.
  *
- * \param dst the SDL_Surface structure that is the drawing target
+ * \param dst the SDL_Surface structure that is the drawing target.
  * \param rects an array of SDL_Rects representing the rectangles to fill.
- * \param count the number of rectangles in the array
- * \param color the color to fill with
+ * \param count the number of rectangles in the array.
+ * \param color the color to fill with.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -913,10 +914,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL
  *       source color key.
  * ```
  *
- * \param src the SDL_Surface structure to be copied from
+ * \param src the SDL_Surface structure to be copied from.
  * \param srcrect the SDL_Rect structure representing the rectangle to be
- *                copied, or NULL to copy the entire surface
- * \param dst the SDL_Surface structure that is the blit target
+ *                copied, or NULL to copy the entire surface.
+ * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the x and y position in
  *                the destination surface. On input the width and height are
  *                ignored (taken from srcrect), and on output this is filled
@@ -940,12 +941,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect
  * This is a semi-private blit function and it performs low-level surface
  * blitting, assuming the input rectangles have already been clipped.
  *
- * \param src the SDL_Surface structure to be copied from
+ * \param src the SDL_Surface structure to be copied from.
  * \param srcrect the SDL_Rect structure representing the rectangle to be
- *                copied, or NULL to copy the entire surface
- * \param dst the SDL_Surface structure that is the blit target
+ *                copied, or NULL to copy the entire surface.
+ * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
- *                the destination surface
+ *                the destination surface.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -965,13 +966,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const
  * Using SDL_SCALEMODE_NEAREST: fast, low quality. Using SDL_SCALEMODE_LINEAR:
  * bilinear scaling, slower, better quality, only 32BPP.
  *
- * \param src the SDL_Surface structure to be copied from
+ * \param src the SDL_Surface structure to be copied from.
  * \param srcrect the SDL_Rect structure representing the rectangle to be
- *                copied
- * \param dst the SDL_Surface structure that is the blit target
+ *                copied.
+ * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
- *                the destination surface
- * \param scaleMode scale algorithm to be used
+ *                the destination surface.
+ * \param scaleMode scale algorithm to be used.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -985,14 +986,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, const SDL_Rect
  * Perform a scaled blit to a destination surface, which may be of a different
  * format.
  *
- * \param src the SDL_Surface structure to be copied from
+ * \param src the SDL_Surface structure to be copied from.
  * \param srcrect the SDL_Rect structure representing the rectangle to be
- *                copied
- * \param dst the SDL_Surface structure that is the blit target
+ *                copied.
+ * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
  *                the destination surface, filled with the actual rectangle
- *                used after clipping
- * \param scaleMode the SDL_ScaleMode to be used
+ *                used after clipping.
+ * \param scaleMode the SDL_ScaleMode to be used.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1012,13 +1013,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD
  * This is a semi-private function and it performs low-level surface blitting,
  * assuming the input rectangles have already been clipped.
  *
- * \param src the SDL_Surface structure to be copied from
+ * \param src the SDL_Surface structure to be copied from.
  * \param srcrect the SDL_Rect structure representing the rectangle to be
- *                copied
- * \param dst the SDL_Surface structure that is the blit target
+ *                copied.
+ * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
- *                the destination surface
- * \param scaleMode scale algorithm to be used
+ *                the destination surface.
+ * \param scaleMode scale algorithm to be used.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1041,17 +1042,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src,
  * Like SDL_GetRGBA, this uses the entire 0..255 range when converting color
  * components from pixel formats with less than 8 bits per RGB component.
  *
- * \param surface the surface to read
- * \param x the horizontal coordinate, 0 <= x < width
- * \param y the vertical coordinate, 0 <= y < height
+ * \param surface the surface to read.
+ * \param x the horizontal coordinate, 0 <= x < width.
+ * \param y the vertical coordinate, 0 <= y < height.
  * \param r a pointer filled in with the red channel, 0-255, or NULL to ignore
- *          this channel
+ *          this channel.
  * \param g a pointer filled in with the green channel, 0-255, or NULL to
- *          ignore this channel
+ *          ignore this channel.
  * \param b a pointer filled in with the blue channel, 0-255, or NULL to
- *          ignore this channel
+ *          ignore this channel.
  * \param a a pointer filled in with the alpha channel, 0-255, or NULL to
- *          ignore this channel
+ *          ignore this channel.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_system.h

@@ -80,8 +80,8 @@ typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
  * message should continue to be processed, or SDL_FALSE to prevent further
  * processing.
  *
- * \param callback The SDL_WindowsMessageHook function to call.
- * \param userdata a pointer to pass to every iteration of `callback`
+ * \param callback the SDL_WindowsMessageHook function to call.
+ * \param userdata a pointer to pass to every iteration of `callback`.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -100,7 +100,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo
  * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
  * controls on which monitor a full screen application will appear.
  *
- * \param displayID the instance of the display to query
+ * \param displayID the instance of the display to query.
  * \returns the D3D9 adapter index on success or a negative error code on
  *          failure; call SDL_GetError() for more information.
  *
@@ -119,9 +119,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex(SDL_DisplayID displ
  * `EnumOutputs` respectively to get the objects required to create a DX10 or
  * DX11 device and swap chain.
  *
- * \param displayID the instance of the display to query
- * \param adapterIndex a pointer to be filled in with the adapter index
- * \param outputIndex a pointer to be filled in with the output index
+ * \param displayID the instance of the display to query.
+ * \param adapterIndex a pointer to be filled in with the adapter index.
+ * \param outputIndex a pointer to be filled in with the output index.
  * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
  *          for more information.
  *
@@ -145,8 +145,8 @@ typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
  * should continue to be processed, or SDL_FALSE to prevent further
  * processing.
  *
- * \param callback The SDL_X11EventHook function to call.
- * \param userdata a pointer to pass to every iteration of `callback`
+ * \param callback the SDL_X11EventHook function to call.
+ * \param userdata a pointer to pass to every iteration of `callback`.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -161,7 +161,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
  * This uses setpriority() if possible, and RealtimeKit if available.
  *
  * \param threadID the Unix thread ID to change priority of.
- * \param priority The new, Unix-specific, priority value.
+ * \param priority the new, Unix-specific, priority value.
  * \returns 0 on success, or -1 on error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -173,10 +173,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int
  *
  * This uses setpriority() if possible, and RealtimeKit if available.
  *
- * \param threadID The Unix thread ID to change priority of.
- * \param sdlPriority The new SDL_ThreadPriority value.
- * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR,
- *                    SCHED_OTHER, etc...)
+ * \param threadID the Unix thread ID to change priority of.
+ * \param sdlPriority the new SDL_ThreadPriority value.
+ * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
+ *                    SCHED_OTHER, etc...).
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -234,9 +234,9 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
  *
  * https://wiki.libsdl.org/SDL3/README/main-functions
  *
- * \param window the window for which the animation callback should be set
+ * \param window the window for which the animation callback should be set.
  * \param interval the number of frames after which **callback** will be
- *                 called
+ *                 called.
  * \param callback the function to call for every frame.
  * \param callbackParam a pointer that is passed to `callback`.
  * \returns 0 on success or a negative error code on failure; call
@@ -253,7 +253,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iOSSetAnimationCallback(SDL_Window * window,
  *
  * This function is only available on Apple iOS.
  *
- * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it
+ * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -475,9 +475,9 @@ typedef void (SDLCALL *SDL_AndroidRequestPermissionCallback)(void *userdata, con
  * like memory running out. Normally there will be a yes or no to the request
  * through the callback.
  *
- * \param permission The permission to request.
- * \param cb The callback to trigger when the request has a response.
- * \param userdata An app-controlled pointer that is passed to the callback.
+ * \param permission the permission to request.
+ * \param cb the callback to trigger when the request has a response.
+ * \param userdata an app-controlled pointer that is passed to the callback.
  * \returns zero if the request was submitted, -1 if there was an error
  *          submitting. The result of the request is only ever reported
  *          through the callback, not this return value.
@@ -502,11 +502,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidRequestPermission(const char *permiss
  *
  * https://developer.android.com/reference/android/view/Gravity
  *
- * \param message text message to be shown
- * \param duration 0=short, 1=long
+ * \param message text message to be shown.
+ * \param duration 0=short, 1=long.
  * \param gravity where the notification should appear on the screen.
- * \param xoffset set this parameter only when gravity >=0
- * \param yoffset set this parameter only when gravity >=0
+ * \param xoffset set this parameter only when gravity >=0.
+ * \param yoffset set this parameter only when gravity >=0.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -521,8 +521,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int du
  *
  * Override "boolean onUnhandledMessage(Message msg)" to handle the message.
  *
- * \param command user command that must be greater or equal to 0x8000
- * \param param user parameter
+ * \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.
  *
@@ -600,7 +600,7 @@ typedef enum SDL_WinRT_DeviceFamily
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
+ * \param pathType the type of path to retrieve, one of SDL_WinRT_Path.
  * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
  *          the path is not available for any reason; call SDL_GetError() for
  *          more information.

include/SDL3/SDL_thread.h

@@ -107,7 +107,7 @@ typedef enum SDL_ThreadPriority {
 /**
  * The function passed to SDL_CreateThread() as the new thread's entry point.
  *
- * \param data what was passed as `data` to SDL_CreateThread()
+ * \param data what was passed as `data` to SDL_CreateThread().
  * \returns a value that can be reported through SDL_WaitThread().
  *
  * \since This datatype is available since SDL 3.0.0.
@@ -173,9 +173,9 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
  * Usually, apps should just call this function the same way on every platform
  * and let the macros hide the details.
  *
- * \param fn the SDL_ThreadFunction function to call in the new thread
- * \param name the name of the thread
- * \param data a pointer that is passed to `fn`
+ * \param fn the SDL_ThreadFunction function to call in the new thread.
+ * \param name the name of the thread.
+ * \param data a pointer that is passed to `fn`.
  * \returns an opaque pointer to the new thread object on success, NULL if the
  *          new thread could not be created; call SDL_GetError() for more
  *          information.
@@ -241,7 +241,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn,
  * Usually, apps should just call this function the same way on every platform
  * and let the macros hide the details.
  *
- * \param props the properties to use
+ * \param props the properties to use.
  * \returns an opaque pointer to the new thread object on success, NULL if the
  *          new thread could not be created; call SDL_GetError() for more
  *          information.
@@ -333,7 +333,7 @@ extern SDL_DECLSPEC SDL_Thread *SDLCALL SDL_CreateThreadWithPropertiesRuntime(SD
  *
  * The returned string follows the SDL_GetStringRule.
  *
- * \param thread the thread to query
+ * \param thread the thread to query.
  * \returns a pointer to a UTF-8 string that names the specified thread, or
  *          NULL if it doesn't have a name.
  *
@@ -366,7 +366,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void);
  * If SDL is running on a platform that does not support threads the return
  * value will always be zero.
  *
- * \param thread the thread to query
+ * \param thread the thread to query.
  * \returns the ID of the specified thread, or the ID of the current thread if
  *          `thread` is NULL.
  *
@@ -383,7 +383,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
  * promote the thread to a higher priority) at all, and some require you to be
  * an administrator account. Be prepared for this to fail.
  *
- * \param priority the SDL_ThreadPriority to set
+ * \param priority the SDL_ThreadPriority to set.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -414,7 +414,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priorit
  * afterward.
  *
  * \param thread the SDL_Thread pointer that was returned from the
- *               SDL_CreateThread() call that started this thread
+ *               SDL_CreateThread() call that started this thread.
  * \param status pointer to an integer that will receive the value returned
  *               from the thread function by its 'return', or NULL to not
  *               receive such value back.
@@ -453,7 +453,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status
  * It is safe to pass NULL to this function; it is a no-op.
  *
  * \param thread the SDL_Thread pointer that was returned from the
- *               SDL_CreateThread() call that started this thread
+ *               SDL_CreateThread() call that started this thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -480,7 +480,7 @@ extern SDL_DECLSPEC SDL_TLSID SDLCALL SDL_CreateTLS(void);
 /**
  * Get the current thread's value associated with a thread local storage ID.
  *
- * \param id the thread local storage ID
+ * \param id the thread local storage ID.
  * \returns the value associated with the ID for the current thread or NULL if
  *          no value has been set; call SDL_GetError() for more information.
  *
@@ -513,8 +513,8 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value);
  * `destructor` can be NULL; it is assumed that `value` does not need to be
  * cleaned up if so.
  *
- * \param id the thread local storage ID
- * \param value the value to associate with the ID for the current thread
+ * \param id the thread local storage ID.
+ * \param value the value to associate with the ID for the current thread.
  * \param destructor a function called when the thread exits, to free the
  *                   value. Can be NULL.
  * \returns 0 on success or a negative error code on failure; call

include/SDL3/SDL_time.h

@@ -92,9 +92,9 @@ typedef enum SDL_TimeFormat
  * preference outside of your program.
  *
  * \param dateFormat a pointer to the SDL_DateFormat to hold the returned date
- *                   format, may be NULL
+ *                   format, may be NULL.
  * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
- *                   format, may be NULL
+ *                   format, may be NULL.
  * \returns 0 on success or -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -106,7 +106,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
  * Gets the current value of the system realtime clock in nanoseconds since
  * Jan 1, 1970 in Universal Coordinated Time (UTC).
  *
- * \param ticks the SDL_Time to hold the returned tick count
+ * \param ticks the SDL_Time to hold the returned tick count.
  * \returns 0 on success or -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -118,11 +118,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
  * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in
  * the SDL_DateTime format.
  *
- * \param ticks the SDL_Time to be converted
- * \param dt the resulting SDL_DateTime
+ * \param ticks the SDL_Time to be converted.
+ * \param dt the resulting SDL_DateTime.
  * \param localTime the resulting SDL_DateTime will be expressed in local time
  *                  if true, otherwise it will be in Universal Coordinated
- *                  Time (UTC)
+ *                  Time (UTC).
  * \returns 0 on success or -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -136,8 +136,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
  * This function ignores the day_of_week member of the SDL_DateTime struct, so
  * it may remain unset.
  *
- * \param dt the source SDL_DateTime
- * \param ticks the resulting SDL_Time
+ * \param dt the source SDL_DateTime.
+ * \param ticks the resulting SDL_Time.
  * \returns 0 on success or -1 on error; call SDL_GetError() for more
  *          information.
  *
@@ -151,11 +151,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_T
  *
  * This function fills in the two 32-bit values of the FILETIME structure.
  *
- * \param ticks the time to convert
+ * \param ticks the time to convert.
  * \param dwLowDateTime a pointer filled in with the low portion of the
- *                      Windows FILETIME value
+ *                      Windows FILETIME value.
  * \param dwHighDateTime a pointer filled in with the high portion of the
- *                       Windows FILETIME value
+ *                       Windows FILETIME value.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -168,9 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow
  * This function takes the two 32-bit values of the FILETIME structure as
  * parameters.
  *
- * \param dwLowDateTime the low portion of the Windows FILETIME value
- * \param dwHighDateTime the high portion of the Windows FILETIME value
- * \returns the converted SDL time
+ * \param dwLowDateTime the low portion of the Windows FILETIME value.
+ * \param dwHighDateTime the high portion of the Windows FILETIME value.
+ * \returns the converted SDL time.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -179,8 +179,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
 /**
  * Get the number of days in a month for a given year.
  *
- * \param year the year
- * \param month the month [1-12]
+ * \param year the year.
+ * \param month the month [1-12].
  * \returns the number of days in the requested month, otherwise -1; call
  *          SDL_GetError() for more information.
  *
@@ -191,9 +191,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
 /**
  * Get the day of year for a calendar date.
  *
- * \param year the year component of the date
- * \param month the month component of the date
- * \param day the day component of the date
+ * \param year the year component of the date.
+ * \param month the month component of the date.
+ * \param day the day component of the date.
  * \returns the day of year [0-365] if the date is valid, otherwise -1; call
  *          SDL_GetError() for more information.
  *
@@ -204,9 +204,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
 /**
  * Get the day of week for a calendar date.
  *
- * \param year the year component of the date
- * \param month the month component of the date
- * \param day the day component of the date
+ * \param year the year component of the date.
+ * \param month the month component of the date.
+ * \param day the day component of the date.
  * \returns a value between 0 and 6 (0 being Sunday) if the date is valid,
  *          otherwise -1; call SDL_GetError() for more information.
  *

include/SDL3/SDL_timer.h

@@ -105,7 +105,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
  * waits at least the specified time, but possibly longer due to OS
  * scheduling.
  *
- * \param ms the number of milliseconds to delay
+ * \param ms the number of milliseconds to delay.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -118,7 +118,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
  * waits at least the specified time, but possibly longer due to OS
  * scheduling.
  *
- * \param ns the number of nanoseconds to delay
+ * \param ns the number of nanoseconds to delay.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -141,7 +141,7 @@ typedef Uint32 SDL_TimerID;
  *
  * \param userdata an arbitrary pointer provided by the app through
  *                 SDL_AddTimer, for its own use.
- * \param timerID the current timer being processed
+ * \param timerID the current timer being processed.
  * \param interval the current callback time interval.
  * \returns the new callback time interval, or 0 to disable further runs of
  *          the callback.
@@ -178,10 +178,10 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID,
  * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
  * callback needs to adjust for variances.
  *
- * \param interval the timer delay, in milliseconds, passed to `callback`
+ * \param interval the timer delay, in milliseconds, passed to `callback`.
  * \param callback the SDL_TimerCallback function to call when the specified
- *                 `interval` elapses
- * \param userdata a pointer that is passed to `callback`
+ *                 `interval` elapses.
+ * \param userdata a pointer that is passed to `callback`.
  * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
  *          information.
  *
@@ -204,7 +204,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC
  *
  * \param userdata an arbitrary pointer provided by the app through
  *                 SDL_AddTimer, for its own use.
- * \param timerID the current timer being processed
+ * \param timerID the current timer being processed.
  * \param interval the current callback time interval.
  * \returns the new callback time interval, or 0 to disable further runs of
  *          the callback.
@@ -241,10 +241,10 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI
  * time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your
  * callback needs to adjust for variances.
  *
- * \param interval the timer delay, in nanoseconds, passed to `callback`
+ * \param interval the timer delay, in nanoseconds, passed to `callback`.
  * \param callback the SDL_TimerCallback function to call when the specified
- *                 `interval` elapses
- * \param userdata a pointer that is passed to `callback`
+ *                 `interval` elapses.
+ * \param userdata a pointer that is passed to `callback`.
  * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
  *          information.
  *
@@ -260,7 +260,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi
 /**
  * Remove a timer created with SDL_AddTimer().
  *
- * \param id the ID of the timer to remove
+ * \param id the ID of the timer to remove.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_touch.h

@@ -109,8 +109,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touch
 /**
  * Get the type of the given touch device.
  *
- * \param touchID the ID of a touch device
- * \returns touch device type
+ * \param touchID the ID of a touch device.
+ * \returns touch device type.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -119,7 +119,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
 /**
  * Get a list of active fingers for a given touch device.
  *
- * \param touchID the ID of a touch device
+ * \param touchID the ID of a touch device.
  * \param count a pointer filled in with the number of fingers returned, can
  *              be NULL.
  * \returns a NULL terminated array of SDL_Finger pointers which should be

include/SDL3/SDL_vulkan.h

@@ -93,7 +93,7 @@ struct VkAllocationCallbacks;
  * supported. Either do not link to the Vulkan loader or link to a dynamic
  * library version.
  *
- * \param path The platform dependent Vulkan loader library name or NULL
+ * \param path the platform dependent Vulkan loader library name or NULL.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -166,12 +166,12 @@ extern SDL_DECLSPEC char const* const* SDLCALL SDL_Vulkan_GetInstanceExtensions(
  * If `allocator` is NULL, Vulkan will use the system default allocator. This
  * argument is passed directly to Vulkan and isn't used by SDL itself.
  *
- * \param window The window to which to attach the Vulkan surface
- * \param instance The Vulkan instance handle
- * \param allocator A VkAllocationCallbacks struct, which lets the app set the
+ * \param window the window to which to attach the Vulkan surface.
+ * \param instance the Vulkan instance handle.
+ * \param allocator a VkAllocationCallbacks struct, which lets the app set the
  *                  allocator that creates the surface. Can be NULL.
- * \param surface A pointer to a VkSurfaceKHR handle to output the newly
- *                created surface
+ * \param surface a pointer to a VkSurfaceKHR handle to output the newly
+ *                created surface.
  * \returns SDL_TRUE on success, SDL_FALSE on error.
  *
  * \since This function is available since SDL 3.0.0.
@@ -197,9 +197,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window
  * If `allocator` is NULL, Vulkan will use the system default allocator. This
  * argument is passed directly to Vulkan and isn't used by SDL itself.
  *
- * \param instance The Vulkan instance handle
- * \param surface VkSurfaceKHR handle to destroy
- * \param allocator A VkAllocationCallbacks struct, which lets the app set the
+ * \param instance the Vulkan instance handle.
+ * \param surface vkSurfaceKHR handle to destroy.
+ * \param allocator a VkAllocationCallbacks struct, which lets the app set the
  *                  allocator that destroys the surface. Can be NULL.
  *
  * \since This function is available since SDL 3.0.0.