Add missing '\param' documentation

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();

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

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 */
 

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.
  *

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.
  *

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.
  *

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.

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.

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);

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

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.

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.
  *