Add missing parameters and return types to SDL2 header docs (#13162)

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,6 +862,10 @@ 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);
@@ -865,6 +873,15 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameCont
 /**
  * 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,

include/SDL_surface.h

@@ -801,14 +801,13 @@ extern DECLSPEC int SDLCALL SDL_FillRect
 extern DECLSPEC int SDLCALL SDL_FillRects
     (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
 
-/* !!! FIXME: merge this documentation with the wiki */
-
 /**
  * Performs a fast blit from the source surface to the destination surface.
  *
  * This assumes that the source and destination rectangles are the same size.
- * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
- * `dst`) is copied. The final blit rectangle is saved in `dstrect` after all
+ * `dstrect`'s width and height are ignored, only its position is used. If
+ * either `srcrect` or `dstrect` are NULL, the entire surface (`src` or `dst`)
+ * is copied. The final blit rectangle is saved in `dstrect` after all
  * clipping is performed.
  *
  * The blit function should not be called on a locked surface.
@@ -859,7 +858,17 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  * You should call SDL_BlitSurface() unless you know exactly how SDL blitting
  * works internally and how to use the other blit functions.
  *
- * \returns 0 if the blit is successful, otherwise it returns -1.
+ * \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.
+ * \param dstrect the SDL_Rect structure representing the x and y position in
+ *                the destination surface, or NULL for (0,0). The width and
+ *                height are ignored, and are copied from `srcrect`. If you
+ *                want a specific width and height, you should use
+ *                SDL_BlitScaled().
+ * \returns 0 if the blit is successful or a negative error code on failure;
+ *          call SDL_GetError() for more information.
  */
 #define SDL_BlitSurface SDL_UpperBlit
 
@@ -869,6 +878,18 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
  * macro for this function with a less confusing name.
  *
+ * \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.
+ * \param dstrect the SDL_Rect structure representing the x and y position in
+ *                the destination surface, or NULL for (0,0). The width and
+ *                height are ignored, and are copied from `srcrect`. If you
+ *                want a specific width and height, you should use
+ *                SDL_BlitScaled().
+ * \returns 0 if the blit is successful or a negative error code on failure;
+ *          call SDL_GetError() for more information.
+ *
  * \since This function is available since SDL 2.0.0.
  *
  * \sa SDL_BlitSurface
@@ -910,6 +931,13 @@ extern DECLSPEC int SDLCALL SDL_LowerBlit
  *
  * Please use SDL_BlitScaled() instead.
  *
+ * \param src the surface to be copied from.
+ * \param srcrect the rectangle to be copied.
+ * \param dst the surface that is the blit target.
+ * \param dstrect the rectangle that is copied into.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
  * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
@@ -920,6 +948,13 @@ extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
 /**
  * Perform bilinear scaling between two surfaces of the same format, 32BPP.
  *
+ * \param src the surface to be copied from.
+ * \param srcrect the rectangle to be copied.
+ * \param dst the surface that is the blit target.
+ * \param dstrect the rectangle that is copied into.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
  * \since This function is available since SDL 2.0.16.
  */
 extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
@@ -934,6 +969,15 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
  * SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is
  * merely a macro for this function with a less confusing name.
  *
+ * \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.
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ *                copied into, or NULL to copy into the entire surface.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
  * \since This function is available since SDL 2.0.0.
  *
  * \sa SDL_BlitScaled
@@ -971,6 +1015,8 @@ extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
 /**
  * Set the YUV conversion mode
  *
+ * \param mode the YUV conversion mode.
+ *
  * \since This function is available since SDL 2.0.8.
  */
 extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
@@ -978,6 +1024,8 @@ extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mo
 /**
  * Get the YUV conversion mode
  *
+ * \returns YUV conversion mode.
+ *
  * \since This function is available since SDL 2.0.8.
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
@@ -986,6 +1034,10 @@ 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 the resolution width.
+ * \param height the resolution height.
+ * \returns YUV conversion mode.
+ *
  * \since This function is available since SDL 2.0.8.
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);

include/SDL_system.h

@@ -463,6 +463,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int durati
  *
  * \param command user command that must be greater or equal to 0x8000.
  * \param param user parameter.
+ * \returns 0 on success, otherwise -1.
  *
  * \since This function is available since SDL 2.0.22.
  */

include/SDL_touch.h

@@ -99,6 +99,10 @@ 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, or NULL on failure; call SDL_GetError() for
+ *          more information.
+ *
  * \since This function is available since SDL 2.0.22.
  */
 extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
@@ -106,6 +110,9 @@ 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 2.0.10.
  */
 extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);

include/SDL_video.h

@@ -1315,6 +1315,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
 /**
  * Return whether the window has a surface associated with it.
  *
+ * \param window the window to query.
  * \returns SDL_TRUE if there is a surface associated with the window, or
  *          SDL_FALSE otherwise.
  *