Add missing parameters and return types to SDL2 header docs

include/SDL_audio.h

@@ -1059,6 +1059,9 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *bu
  * 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 bytes available.
+ *
  * \since This function is available since SDL 2.0.7.
  *
  * \sa SDL_NewAudioStream
@@ -1078,6 +1081,9 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(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, otherwise -1.
+ *
  * \since This function is available since SDL 2.0.7.
  *
  * \sa SDL_NewAudioStream
@@ -1092,6 +1098,8 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
 /**
  * Clear any pending data in the stream without converting it
  *
+ * \param stream the audio stream to clear.
+ *
  * \since This function is available since SDL 2.0.7.
  *
  * \sa SDL_NewAudioStream
@@ -1106,6 +1114,8 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
 /**
  * Free an audio stream
  *
+ * \param stream the audio stream to free.
+ *
  * \since This function is available since SDL 2.0.7.
  *
  * \sa SDL_NewAudioStream

include/SDL_gamecontroller.h

@@ -226,6 +226,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(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.
  *
@@ -850,6 +851,9 @@ extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *ga
 /**
  * Get the number of touchpads on a game controller.
  *
+ * \param gamecontroller a controller.
+ * \returns number of touchpads.
+ *
  * \since This function is available since SDL 2.0.14.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
@@ -858,13 +862,26 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController
  * Get the number of supported simultaneous fingers on a touchpad on a game
  * controller.
  *
+ * \param gamecontroller a controller.
+ * \param touchpad a touchpad.
+ * \returns number of supported simultaneous fingers.
+ *
  * \since This function is available since SDL 2.0.14.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
 
 /**
  * Get the current state of a finger on a touchpad on a game controller.
  *
+ * \param gamecontroller a controller.
+ * \param touchpad a touchpad.
+ * \param finger a finger.
+ * \param state a pointer filled with the finger state.
+ * \param x a pointer filled with the x position.
+ * \param y a pointer filled with the y position.
+ * \param pressure a pointer filled with pressure value.
+ * \returns 0 on success or negative on failure.
+ *
  * \since This function is available since SDL 2.0.14.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);

include/SDL_hidapi.h

@@ -227,6 +227,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 boolean exclusive.
  * \returns a pointer to a SDL_hid_device object on success or NULL on
  *          failure.
  *

include/SDL_joystick.h

@@ -214,6 +214,9 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickPathForIndex(int device_index);
  * Get the player index of a joystick, or -1 if it's not available This can be
  * called before any joysticks are opened.
  *
+ * \param device_index device index.
+ * \returns player index, or -1 if not available.
+ *
  * \since This function is available since SDL 2.0.9.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
@@ -356,6 +359,10 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_ind
 /**
  * Attach a new virtual joystick.
  *
+ * \param type joystick type.
+ * \param naxes number of axes.
+ * \param nbuttons number of buttons.
+ * \param nhats number of hats.
  * \returns the joystick's device index, or -1 if an error occurred.
  *
  * \since This function is available since SDL 2.0.14.
@@ -409,6 +416,7 @@ typedef struct SDL_VirtualJoystickDesc
 /**
  * Attach a new virtual joystick with extended properties.
  *
+ * \param desc joystick description.
  * \returns the joystick's device index, or -1 if an error occurred.
  *
  * \since This function is available since SDL 2.24.0.

include/SDL_keyboard.h

@@ -298,6 +298,9 @@ extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
 /**
  * Returns if an IME Composite or Candidate window is currently shown.
  *
+ * \returns SDL_TRUE if an IME Composite or Candidate window is currently
+ *          shown else SDL_FALSE.
+ *
  * \since This function is available since SDL 2.0.22.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void);

include/SDL_log.h

@@ -163,8 +163,7 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(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.
  *

include/SDL_metal.h

@@ -59,6 +59,9 @@ 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 2.0.12.
  *
  * \sa SDL_Metal_DestroyView
@@ -72,6 +75,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 SDL_MetalView object.
+ *
  * \since This function is available since SDL 2.0.12.
  *
  * \sa SDL_Metal_CreateView
@@ -81,6 +86,9 @@ extern 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.
+ *
  * \since This function is available since SDL 2.0.14.
  *
  * \sa SDL_Metal_CreateView

include/SDL_rect.h

@@ -106,6 +106,10 @@ typedef struct SDL_FRect
 
 /**
  * Returns true if point resides inside a rectangle.
+ *
+ * \param p the point to test.
+ * \param r the rectangle to test.
+ * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise.
  */
 SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 {
@@ -115,6 +119,9 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 
 /**
  * Returns true if the rectangle has no area.
+ *
+ * \param r the rectangle to test.
+ * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 {
@@ -123,6 +130,10 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 
 /**
  * Returns true if the two rectangles are equal.
+ *
+ * \param a the first rectangle to test.
+ * \param b the second rectangle to test.
+ * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 {
@@ -229,6 +240,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
 
 /**
  * Returns true if point resides inside a rectangle.
+ *
+ * \param p the point to test.
+ * \param r the rectangle to test.
+ * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise.
  */
 SDL_FORCE_INLINE SDL_bool SDL_PointInFRect(const SDL_FPoint *p, const SDL_FRect *r)
 {
@@ -238,6 +253,9 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInFRect(const SDL_FPoint *p, const SDL_FRect
 
 /**
  * Returns true if the rectangle has no area.
+ *
+ * \param r the rectangle to test.
+ * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.
  */
 SDL_FORCE_INLINE SDL_bool SDL_FRectEmpty(const SDL_FRect *r)
 {
@@ -247,6 +265,11 @@ SDL_FORCE_INLINE SDL_bool SDL_FRectEmpty(const SDL_FRect *r)
 /**
  * Returns true if the two rectangles are equal, within some given epsilon.
  *
+ * \param a the first rectangle to test.
+ * \param b the second rectangle to test.
+ * \param epsilon the epsilon value for comparison.
+ * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
+ *
  * \since This function is available since SDL 2.0.22.
  */
 SDL_FORCE_INLINE SDL_bool SDL_FRectEqualsEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
@@ -262,6 +285,10 @@ SDL_FORCE_INLINE SDL_bool SDL_FRectEqualsEpsilon(const SDL_FRect *a, const SDL_F
 /**
  * Returns true if the two rectangles are equal, using a default epsilon.
  *
+ * \param a the first rectangle to test.
+ * \param b the second rectangle to test.
+ * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
+ *
  * \since This function is available since SDL 2.0.22.
  */
 SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b)

include/SDL_stdinc.h

@@ -467,6 +467,11 @@ typedef void (SDLCALL *SDL_free_func)(void *mem);
 /**
  * Get the original 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.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func,
@@ -477,6 +482,11 @@ extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *mal
 /**
  * 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.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
@@ -487,6 +497,13 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
 /**
  * Replace SDL's memory allocation functions with a custom set
  *
+ * \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 -1 on failure; call SDL_GetError() for more
+ *          information.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
@@ -497,6 +514,8 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
 /**
  * Get the number of outstanding (unfreed) allocations
  *
+ * \returns number of unfreed allocations.
+ *
  * \since This function is available since SDL 2.0.7.
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
@@ -715,6 +734,12 @@ extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
  * This function converts a buffer or string between encodings in one pass,
  * returning a string that must be freed with SDL_free() or NULL on error.
  *
+ * \param tocode the character encoding of the output string.
+ * \param fromcode the character encoding of data in `inbuf`.
+ * \param inbuf the string to convert to a different encoding.
+ * \param inbytesleft the size of the input string _in bytes_.
+ * \returns a new string, converted to the new encoding, or NULL on error.
+ *
  * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
@@ -806,6 +831,11 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B
  *
  * Otherwise store a * b via ret and return 0.
  *
+ * \param a the multiplicand.
+ * \param b the multiplier.
+ * \param ret on non-overflow output, stores the multiplication result.
+ * \returns -1 on overflow, 0 if result is multiplied without overflow.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a,
@@ -837,6 +867,11 @@ SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a,
  *
  * Otherwise store a + b via ret and return 0.
  *
+ * \param a the first addend.
+ * \param b the second addend.
+ * \param ret on non-overflow output, stores the addition result.
+ * \returns false on overflow, true if result is added without overflow.
+ *
  * \since This function is available since SDL 2.24.0.
  */
 SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a,