Sync wiki -> headers.

include/SDL3/SDL_assert.h

@@ -137,7 +137,9 @@ typedef struct SDL_AssertData
 #if (SDL_ASSERT_LEVEL > 0)
 
 /**
- * Never call this directly. Use the SDL_assert* macros.
+ * Never call this directly.
+ *
+ * Use the SDL_assert* macros.
  *
  * \param data assert data structure
  * \param func function name

include/SDL3/SDL_audio.h

@@ -811,7 +811,7 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
 /**
  * Clear any pending data in the stream without converting it
  *
- * \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.
  *
@@ -830,6 +830,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
@@ -1149,7 +1150,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
  * \param dst_channels The number of channels of the desired audio output
  * \param dst_rate The sampling rate of the desired audio output
  * \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.
+ *                 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
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.

include/SDL3/SDL_error.h

@@ -148,6 +148,7 @@ typedef enum
     SDL_UNSUPPORTED,
     SDL_LASTERROR
 } SDL_errorcode;
+
 /**
  * SDL_Error()
  *

include/SDL3/SDL_joystick.h

@@ -918,7 +918,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U
  * DualShock 4 controller.
  *
  * \param joystick The joystick to query
- * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE
+ *          otherwise.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_locale.h

@@ -84,7 +84,7 @@ typedef struct SDL_Locale
  * preferred locales.
  *
  * \returns array of locales, terminated with a locale with a NULL language
- *         field. Will return NULL on error.
+ *          field. Will return NULL on error.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_main.h

@@ -192,7 +192,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
  * \param reserved should be NULL (reserved for future use, will probably be
  *                 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
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_render.h

@@ -235,9 +235,9 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
  * need a specific renderer, specify NULL and SDL will attempt to chooes the
  * best option for you, based on what is available on the user's system.
  *
- * By default the rendering size matches the window size in screen coordinates,
- * but you can call SDL_SetRenderLogicalPresentation() to enable high DPI
- * rendering or change the content size and scaling options.
+ * By default the rendering size matches the window size in screen
+ * coordinates, but you can call SDL_SetRenderLogicalPresentation() to enable
+ * high DPI rendering or change the content size and scaling options.
  *
  * \param window the window where rendering is displayed
  * \param name the name of the rendering driver to initialize, or NULL to
@@ -337,8 +337,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderWindowSize(SDL_Renderer *renderer, int
 /**
  * Get the output size in pixels of a rendering context.
  *
- * This returns the true output size in pixels, ignoring any render targets
- * or logical size and presentation.
+ * This returns the true output size in pixels, ignoring any render targets or
+ * logical size and presentation.
  *
  * \param renderer the rendering context
  * \param w a pointer filled in with the width in pixels
@@ -355,9 +355,9 @@ extern DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int
 /**
  * Get the current output size in pixels of a rendering context.
  *
- * If a rendering target is active, this will return the size of the
- * rendering target in pixels, otherwise if a logical size is set, it will
- * return the logical size, otherwise it will return the value of
+ * If a rendering target is active, this will return the size of the rendering
+ * target in pixels, otherwise if a logical size is set, it will return the
+ * logical size, otherwise it will return the value of
  * SDL_GetRenderOutputSize().
  *
  * \param renderer the rendering context
@@ -610,7 +610,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *u
  *
  * \param texture the texture to query.
  * \returns the pointer associated with the texture, or NULL if the texture is
- *         not valid.
+ *          not valid.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -836,9 +836,9 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer)
 /**
  * Set a device independent resolution and presentation mode for rendering.
  *
- * This function sets the width and height of the logical rendering output.
- * A render target is created at the specified size and used for rendering
- * and then copied to the output during presentation.
+ * This function sets the width and height of the logical rendering output. A
+ * render target is created at the specified size and used for rendering and
+ * then copied to the output during presentation.
  *
  * When a renderer is created, the logical size is set to match the window
  * size in screen coordinates. The actual output size may be higher pixel
@@ -869,8 +869,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *rende
 /**
  * Get device independent resolution and presentation mode for rendering.
  *
- * This function gets the width and height of the logical rendering output,
- * or the output size in pixels if a logical resolution is not enabled.
+ * This function gets the width and height of the logical rendering output, or
+ * the output size in pixels if a logical resolution is not enabled.
  *
  * \param renderer the rendering context
  * \param w an int to be filled with the width
@@ -910,8 +910,10 @@ extern DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *render
  * \param renderer the rendering context
  * \param x the x coordinate in render coordinates
  * \param y the y coordinate in render coordinates
- * \param window_x a pointer filled with the x coordinate in window coordinates
- * \param window_y a pointer filled with the y coordinate in window coordinates
+ * \param window_x a pointer filled with the x coordinate in window
+ *                 coordinates
+ * \param window_y a pointer filled with the y coordinate in window
+ *                 coordinates
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_shape.h

@@ -72,8 +72,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,un
  * Return whether the given window is a shaped window.
  *
  * \param window The window to query for being shaped.
- * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
- *         the window is unshaped or NULL.
+ * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE
+ *          if the window is unshaped or NULL.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -117,8 +117,8 @@ typedef struct SDL_WindowShapeMode {
  * \param shape A surface encoding the desired shape for the window.
  * \param shape_mode The parameters to set for the shaped window.
  * \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
- *         argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
- *         not reference a valid shaped window.
+ *          argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
+ *          not reference a valid shaped window.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -134,10 +134,10 @@ extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *s
  * \param shape_mode An empty shape-mode structure to fill, or NULL to check
  *                   whether the window has a shape.
  * \returns 0 if the window has a shape and, provided shape_mode was not NULL,
- *         shape_mode has been filled with the mode data,
- *         SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
- *         window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
- *         shapeable window currently lacking a shape.
+ *          shape_mode has been filled with the mode data,
+ *          SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
+ *          window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
+ *          shapeable window currently lacking a shape.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_surface.h

@@ -797,6 +797,8 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
  * Perform a fast, low quality, stretch blit between two surfaces of the same
  * format.
  *
+ * **WARNING**: Please use SDL_BlitScaled() instead.
+ *
  * \param src the SDL_Surface structure to be copied from
  * \param srcrect the SDL_Rect structure representing the rectangle to be
  *                copied
@@ -806,8 +808,6 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
- * Please use SDL_BlitScaled() instead.
- *
  * \since This function is available since SDL 3.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,

include/SDL3/SDL_system.h

@@ -385,7 +385,8 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
  *
  * If external storage is currently unavailable, this will return 0.
  *
- * \param state filled with the current state of external storage. 0 if external storage is currently unavailable.
+ * \param state filled with the current state of external storage. 0 if
+ *              external storage is currently unavailable.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *

include/SDL3/SDL_touch.h

@@ -121,7 +121,8 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t
  *
  * \param touchID the ID of a touch device
  * \returns the number of active fingers for a given touch device on success
- *          or a negative error code on failure; call SDL_GetError() for more information.
+ *          or a negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *

include/SDL3/SDL_video.h

@@ -392,6 +392,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
  * Get a list of fullscreen display modes available on a display.
  *
  * The display modes are sorted in this priority:
+ *
  * - screen_w -> largest to smallest
  * - screen_h -> largest to smallest
  * - pixel_w -> largest to smallest
@@ -402,9 +403,9 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
  *
  * \param displayID the instance ID of the display to query
  * \param count a pointer filled in with the number of displays returned
- * \returns a NULL terminated array of display mode pointers which should be freed
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
- *          details.
+ * \returns a NULL terminated array of display mode pointers which should be
+ *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ *          more details.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -425,8 +426,11 @@ extern DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayModes(SD
  * \param displayID the instance ID of the display to query
  * \param w the width in pixels of the desired display mode
  * \param h the height in pixels of the desired display mode
- * \param refresh_rate the refresh rate of the desired display mode, or 0.0f for the desktop refresh rate
- * \returns a pointer to the closest display mode equal to or larger than the desired mode, or NULL on error; call SDL_GetError() for more information.
+ * \param refresh_rate the refresh rate of the desired display mode, or 0.0f
+ *                     for the desktop refresh rate
+ * \returns a pointer to the closest display mode equal to or larger than the
+ *          desired mode, or NULL on error; call SDL_GetError() for more
+ *          information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -525,7 +529,9 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window
  * SDL_SetWindowSize().
  *
  * \param window the window to affect
- * \param mode a pointer to the display mode to use, which can be NULL for desktop mode, or one of the fullscreen modes returned by SDL_GetFullscreenDisplayModes().
+ * \param mode a pointer to the display mode to use, which can be NULL for
+ *             desktop mode, or one of the fullscreen modes returned by
+ *             SDL_GetFullscreenDisplayModes().
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -822,8 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, in
  * The window size in screen coordinates may differ from the size in pixels if
  * the window is on a high density display (one with an OS scaling factor).
  *
- * This only affects the size of the window when not in fullscreen mode. To change
- * the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
+ * This only affects the size of the window when not in fullscreen mode. To
+ * change the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
  *
  * \param window the window to change
  * \param w the width of the window, must be > 0
@@ -1127,8 +1133,8 @@ extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
 /**
  * Set a window's fullscreen state.
  *
- * By default a window in fullscreen state uses fullscreen desktop mode,
- * but a specific display mode can be set using SDL_SetWindowFullscreenMode().
+ * By default a window in fullscreen state uses fullscreen desktop mode, but a
+ * specific display mode can be set using SDL_SetWindowFullscreenMode().
  *
  * \param window the window to change
  * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode