SDL: Add missing '\param' documentation

From 43c08170afe93d1b23d41870466353760b761ff4 Mon Sep 17 00:00:00 2001
From: Sylvain <[EMAIL REDACTED]>
Date: Sun, 12 Feb 2023 09:40:39 +0100
Subject: [PATCH] Add missing '\param' documentation

---
 include/SDL3/SDL_assert.h      | 23 ++++++++++++++++-------
 include/SDL3/SDL_audio.h       |  3 +++
 include/SDL3/SDL_error.h       |  7 ++++++-
 include/SDL3/SDL_gamepad.h     | 11 +++++++++++
 include/SDL3/SDL_hidapi.h      |  1 +
 include/SDL3/SDL_joystick.h    |  5 +++++
 include/SDL3/SDL_metal.h       |  4 ++++
 include/SDL3/SDL_surface.h     | 16 ++++++++++++++++
 include/SDL3/SDL_test_memory.h |  2 +-
 include/SDL3/SDL_thread.h      | 17 +++++++++++++++++
 include/SDL3/SDL_touch.h       |  2 ++
 include/SDL3/SDL_video.h       |  1 +
 12 files changed, 83 insertions(+), 9 deletions(-)

diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index ad3eb8c8652a..90def7b3d72f 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -130,19 +130,28 @@ typedef struct SDL_AssertData
 
 #if (SDL_ASSERT_LEVEL > 0)
 
-/* Never call this directly. Use the SDL_assert* macros. */
-extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
-                                                             const char *,
-                                                             const char *, int)
+/**
+ * Never call this directly. Use the SDL_assert* macros.
+ *
+ * \param data assert data structure
+ * \param func function name
+ * \param file file name
+ * \param line line number
+ * \returns assert state
+ */
+extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data,
+                                                            const char *func,
+                                                            const char *file, int line)
 #if defined(__clang__)
 #if __has_feature(attribute_analyzer_noreturn)
-/* this tells Clang's static analysis that we're a custom assert function,
-   and that the analyzer should assume the condition was always true past this
-   SDL_assert test. */
    __attribute__((analyzer_noreturn))
 #endif
 #endif
 ;
+/* Previous 'analyzer_noreturn' attribute tells Clang's static analysis that we're a custom assert function,
+   and that the analyzer should assume the condition was always true past this
+   SDL_assert test. */
+
 
 /* the do {} while(0) avoids dangling else problems:
     if (x) SDL_assert(y); else blah();
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 12c1a18f691d..7db605da26ea 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -768,6 +768,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void
  * resample correctly, so this number might be lower than what you expect, or
  * even be zero. Add more data or flush the stream if you need the data now.
  *
+ * \param stream The audio stream to query
  * \returns the number of converted/resampled bytes available.
  *
  * \since This function is available since SDL 3.0.0.
@@ -789,6 +790,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
  * audio gaps in the output. Generally this is intended to signal the end of
  * input, so the complete output becomes available.
  *
+ * \param stream The audio stream to flush
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -824,6 +826,7 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
 /**
  * Free an audio stream
  *
+ * \param stream The audio stream to free
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CreateAudioStream
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index 3f5bcd1945c4..0492eaf4a760 100644
--- a/include/SDL3/SDL_error.h
+++ b/include/SDL3/SDL_error.h
@@ -148,7 +148,12 @@ typedef enum
     SDL_UNSUPPORTED,
     SDL_LASTERROR
 } SDL_errorcode;
-/* SDL_Error() unconditionally returns -1. */
+/**
+ * SDL_Error()
+ *
+ * \param code Error code
+ * \returns unconditionally -1.
+ */
 extern DECLSPEC int SDLCALL SDL_Error(SDL_errorcode code);
 /* @} *//* Internal error functions */
 
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 4f957e598cc5..a3054f5dc2b0 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -232,6 +232,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadMappings(void);
 /**
  * Get the mapping at a particular index.
  *
+ * \param mapping_index mapping index
  * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
  *          the index is out of range.
  *
@@ -843,6 +844,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_Gam
 /**
  * Get the number of touchpads on a gamepad.
  *
+ * \param gamepad a gamepad
  * \returns number of touchpads
  *
  * \since This function is available since SDL 3.0.0.
@@ -853,6 +855,8 @@ extern 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
  *
  * \since This function is available since SDL 3.0.0.
@@ -862,6 +866,13 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepa
 /**
  * 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 x filled with x position
+ * \param y filled with y position
+ * \param pressure filled with pressure value
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h
index ff616c67d101..2043991013a6 100644
--- a/include/SDL3/SDL_hidapi.h
+++ b/include/SDL3/SDL_hidapi.h
@@ -235,6 +235,7 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id,
  * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
  *
  * \param path The path name of the device to open
+ * \param bExclusive exclusive opening (windows only?FIXME)
  * \returns a pointer to a SDL_hid_device object on success or NULL on
  *          failure.
  *
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 3c619c79469a..840f3b5cf251 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -309,6 +309,10 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
 /**
  * Attach a new virtual joystick.
  *
+ * \param type Type of joystick
+ * \param naxes number of axes
+ * \param nbuttons number of buttons
+ * \param nhats number of hats
  * \returns the joystick instance ID, or 0 if an error occurred; call
  *          SDL_GetError() for more information.
  *
@@ -361,6 +365,7 @@ typedef struct SDL_VirtualJoystickDesc
 /**
  * Attach a new virtual joystick with extended properties.
  *
+ * \param desc Joystick description
  * \returns the joystick instance ID, or 0 if an error occurred; call
  *          SDL_GetError() for more information.
  *
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index fc256b26053c..79d0283d262e 100644
--- a/include/SDL3/SDL_metal.h
+++ b/include/SDL3/SDL_metal.h
@@ -58,6 +58,7 @@ 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
  *
  * \since This function is available since SDL 3.0.0.
@@ -73,6 +74,8 @@ extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
  * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
  * called after SDL_CreateWindow.
  *
+ * \param view the view
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_Metal_CreateView
@@ -82,6 +85,7 @@ extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
 /**
  * Get a pointer to the backing CAMetalLayer for the given view.
  *
+ * \param view the view
  * \returns a pointer
  *
  * \since This function is available since SDL 3.0.0.
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 874a9c21ec1e..db12858d2e39 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -795,6 +795,12 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
  * Perform a fast, low quality, stretch blit between two surfaces of the same
  * format.
  *
+ * \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
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ *                copied into
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -810,6 +816,12 @@ extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
 /**
  * Perform bilinear scaling between two surfaces of the same format, 32BPP.
  *
+ * \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
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ *                copied into
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -867,6 +879,8 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled
 /**
  * Set the YUV conversion mode
  *
+ * \param YUV conversion mode
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
@@ -884,6 +898,8 @@ extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
  * Get the YUV conversion mode, returning the correct mode for the resolution
  * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
  *
+ * \param width width
+ * \param height height
  * \returns YUV conversion mode
  *
  * \since This function is available since SDL 3.0.0.
diff --git a/include/SDL3/SDL_test_memory.h b/include/SDL3/SDL_test_memory.h
index 38ef6a9c8a57..da71a0d93db3 100644
--- a/include/SDL3/SDL_test_memory.h
+++ b/include/SDL3/SDL_test_memory.h
@@ -39,7 +39,7 @@ extern "C" {
 
 /**
  * \brief Start tracking SDL memory allocations
- * 
+ *
  * \note This should be called before any other SDL functions for complete tracking coverage
  */
 int SDLTest_TrackAllocations(void);
diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h
index 0d76f28d1fb6..42552e7b458d 100644
--- a/include/SDL3/SDL_thread.h
+++ b/include/SDL3/SDL_thread.h
@@ -118,6 +118,14 @@ typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
 
 
 /*
+ * Create a SDL Thread
+ *
+ * \param fn Thread function
+ * \param name name
+ * \param data some data
+ * \param pfnSDL_CurrentBeginThread begin function
+ * \param pfnSDL_CurrentEndThread end function
+ *
  * \returns SDL_Thread pointer
  */
 extern DECLSPEC SDL_Thread *SDLCALL
@@ -126,6 +134,15 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
                  pfnSDL_CurrentEndThread pfnEndThread);
 
 /*
+ * Create a SDL Thread, with explicit stack size
+ *
+ * \param fn Thread function
+ * \param name name
+ * \param stacksize stack size
+ * \param data some data
+ * \param pfnSDL_CurrentBeginThread begin function
+ * \param pfnSDL_CurrentEndThread end function
+ *
  * \returns SDL_Thread pointer
  */
 extern DECLSPEC SDL_Thread *SDLCALL
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index 00d1aaf20c65..df24da43dce0 100644
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -99,6 +99,7 @@ extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
  * Get the touch device name as reported from the driver or NULL if the index
  * is invalid.
  *
+ * \param index the touch device index
  * \returns touch device name
  *
  * \since This function is available since SDL 3.0.0.
@@ -108,6 +109,7 @@ extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
 /**
  * Get the type of the given touch device.
  *
+ * \param touchID the ID of a touch device
  * \returns touch device type
  *
  * \since This function is available since SDL 3.0.0.
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 3c5e6ca9b1a9..2e273c8bd9b0 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -1842,6 +1842,7 @@ extern DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentEGLConfig(void);
 /**
  * Get the EGL surface associated with the window.
  *
+ * \param window the window to query
  * \returns the EGLSurface pointer associated with the window, or NULL on
  *          failure.
  *