Sync wiki -> headers.

include/SDL3/SDL_pen.h

@@ -147,15 +147,13 @@ typedef enum
 /**
  * Retrieves all pens that are connected to the system.
  *
- * Yields an array of ::SDL_PenID values.  These identify and track pens throughout a session.
- * To track pens across sessions (program restart), use ::SDL_GUID .
+ * Yields an array of ::SDL_PenID values. These identify and track pens
+ * throughout a session. To track pens across sessions (program restart), use
+ * ::SDL_GUID .
  *
- * \param[out] count The number of pens in the array (number of array elements minus 1, i.e., not
- *     counting the terminator 0).
- *
- * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error.
- *     The array must be freed with ::SDL_free().
- *     On a NULL return, ::SDL_GetError() is set.
+ * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
+ *          array must be freed with ::SDL_free(). On a NULL return,
+ *          ::SDL_GetError() is set.
  *
  * \since This function is available since SDL 3.TBD
  */
@@ -168,15 +166,11 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
  * default values.
  *
  * \param instance_id The pen to query.
- * \param[out] x Out-mode parameter for pen x coordinate.  May be NULL.
- * \param[out] y Out-mode parameter for pen y coordinate.  May be NULL.
- * \param[out] axes Out-mode parameter for axis information.  May be null.  The axes are in the same order as for
- *     ::SDL_PenAxis .
  * \param num_axes Maximum number of axes to write to "axes".
- *
- * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK etc.),
- *     possibly ::SDL_PEN_DOWN_MASK, and exactly one of
- *     ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see ::SDL_GetError()).
+ * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
+ *          etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
+ *          ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
+ *          ::SDL_GetError()).
  *
  * \since This function is available since SDL 3.TBD
  */
@@ -186,12 +180,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x,
  * Retrieves an ::SDL_PenID for the given ::SDL_GUID.
  *
  * \param guid A pen GUID.
- *
- * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching SDL_PenID.
+ * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
+ *          SDL_PenID.
  *
  * \since This function is available since SDL 3.TBD
  *
- * \sa SDL_GUID()
+ * \sa SDL_GUID
  */
 extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
 
@@ -199,25 +193,24 @@ extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
  * Retrieves the ::SDL_GUID for a given ::SDL_PenID.
  *
  * \param instance_id The pen to query.
- *
  * \returns The corresponding pen GUID; persistent across multiple sessions.
- *     If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
+ *          If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
  *
  * \since This function is available since SDL 3.TBD
  *
- * \sa SDL_PenForID()
+ * \sa SDL_PenForID
  */
 extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
 
 /**
  * Checks whether a pen is still attached.
  *
- * If a pen is detached, it will not show up for ::SDL_GetPens().
- * Other operations will still be available but may return default values.
+ * If a pen is detached, it will not show up for ::SDL_GetPens(). Other
+ * operations will still be available but may return default values.
  *
  * \param instance_id A pen ID.
- * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is attached, or
- *     SDL_FALSE otherwise.
+ * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
+ *          attached, or SDL_FALSE otherwise.
  *
  * \since This function is available since SDL 3.TBD
  */
@@ -227,14 +220,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
  * Retrieves a human-readable description for a ::SDL_PenID.
  *
  * \param instance_id The pen to query.
- *
- * \returns A string that contains the name of the pen, intended for human consumption.
- *     The string might or might not be localised, depending on platform settings.
- *     It is not guaranteed to be unique; use ::SDL_GetPenGUID() for (best-effort)
- *     unique identifiers.
- *     The pointer is managed by the SDL pen subsystem and must not be deallocated.
- *     The pointer remains valid until SDL is shut down.
- *     Returns NULL on error (cf. ::SDL_GetError())
+ * \returns A string that contains the name of the pen, intended for human
+ *          consumption. The string might or might not be localised, depending
+ *          on platform settings. It is not guaranteed to be unique; use
+ *          ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
+ *          pointer is managed by the SDL pen subsystem and must not be
+ *          deallocated. The pointer remains valid until SDL is shut down.
+ *          Returns NULL on error (cf. ::SDL_GetError())
  *
  * \since This function is available since SDL 3.TBD
  */
@@ -254,10 +246,7 @@ typedef struct SDL_PenCapabilityInfo
  * Retrieves capability flags for a given ::SDL_PenID.
  *
  * \param instance_id The pen to query.
- * \param[out] capabilities Detail information about pen capabilities, such as the number of buttons
- *
- * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES.  Returns 0 on error
- *     (cf. ::SDL_GetError())
+ * \returns a set of capability flags, cf. \link SDL_PEN_CAPABILITIES
  *
  * \since This function is available since SDL 3.TBD
  */
@@ -267,10 +256,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL
  * Retrieves the pen type for a given ::SDL_PenID.
  *
  * \param instance_id The pen to query.
- * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.  Note that the pen type does not
- *     dictate whether the pen tip is ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a pen
- *     is being used for drawing or in eraser mode, check either the pen tip on ::SDL_EVENT_PEN_DOWN, or the
- *     flag ::SDL_PEN_ERASER_MASK in the pen state.
+ * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
+ *          Note that the pen type does not dictate whether the pen tip is
+ *          ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
+ *          pen is being used for drawing or in eraser mode, check either the
+ *          pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
+ *          in the pen state.
+ *
  * \since This function is available since SDL 3.TBD
  */
 extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);

include/SDL3/SDL_properties.h

@@ -231,7 +231,8 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const
  *
  * \param props the properties to query
  * \param name the name of the property to query
- * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is not set.
+ * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
+ *          not set.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -250,7 +251,8 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr
  * \param props the properties to query
  * \param name the name of the property to query
  * \param default_value the default value of the property
- * \returns the value of the property, or `default_value` if it is not set or not a pointer property.
+ * \returns the value of the property, or `default_value` if it is not set or
+ *          not a pointer property.
  *
  * \threadsafety It is safe to call this function from any thread, although
  *               the data returned is not protected and could potentially be
@@ -271,7 +273,8 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char
  * \param props the properties to query
  * \param name the name of the property to query
  * \param default_value the default value of the property
- * \returns the value of the property, or `default_value` if it is not set or not a string property.
+ * \returns the value of the property, or `default_value` if it is not set or
+ *          not a string property.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -285,12 +288,14 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props
 /**
  * Get a number property on a set of properties
  *
- * You can use SDL_GetPropertyType() to query whether the property exists and is a number property.
+ * You can use SDL_GetPropertyType() to query whether the property exists and
+ * is a number property.
  *
  * \param props the properties to query
  * \param name the name of the property to query
  * \param default_value the default value of the property
- * \returns the value of the property, or `default_value` if it is not set or not a number property.
+ * \returns the value of the property, or `default_value` if it is not set or
+ *          not a number property.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -304,12 +309,14 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con
 /**
  * Get a floating point property on a set of properties
  *
- * You can use SDL_GetPropertyType() to query whether the property exists and is a floating point property.
+ * You can use SDL_GetPropertyType() to query whether the property exists and
+ * is a floating point property.
  *
  * \param props the properties to query
  * \param name the name of the property to query
  * \param default_value the default value of the property
- * \returns the value of the property, or `default_value` if it is not set or not a float property.
+ * \returns the value of the property, or `default_value` if it is not set or
+ *          not a float property.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -323,12 +330,14 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const
 /**
  * Get a boolean property on a set of properties
  *
- * You can use SDL_GetPropertyType() to query whether the property exists and is a boolean property.
+ * You can use SDL_GetPropertyType() to query whether the property exists and
+ * is a boolean property.
  *
  * \param props the properties to query
  * \param name the name of the property to query
  * \param default_value the default value of the property
- * \returns the value of the property, or `default_value` if it is not set or not a float property.
+ * \returns the value of the property, or `default_value` if it is not set or
+ *          not a float property.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -356,10 +365,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props,
 extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
 
 typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
+
 /**
  * Enumerate the properties on a set of properties
  *
- * The callback function is called for each property on the set of properties. The properties are locked during enumeration.
+ * The callback function is called for each property on the set of properties.
+ * The properties are locked during enumeration.
  *
  * \param props the properties to query
  * \param callback the function to call for each property

include/SDL3/SDL_render.h

@@ -310,6 +310,7 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
  * Get the properties associated with a renderer.
  *
  * The following properties are provided by SDL:
+ *
  * ```
  * "SDL.renderer.d3d9.device" (pointer) - the IDirect3DDevice9 associated with the renderer
  * "SDL.renderer.d3d11.device" (pointer) - the ID3D11Device associated with the renderer
@@ -423,6 +424,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  * The following properties are provided by SDL:
  *
  * With the direct3d11 renderer:
+ *
  * ```
  * "SDL.texture.d3d11.texture" (pointer) - the ID3D11Texture2D associated with the texture
  * "SDL.texture.d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U plane of a YUV texture
@@ -430,6 +432,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  * ```
  *
  * With the direct3d12 renderer:
+ *
  * ```
  * "SDL.texture.d3d12.texture" (pointer) - the ID3D12Resource associated with the texture
  * "SDL.texture.d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U plane of a YUV texture
@@ -437,6 +440,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  * ```
  *
  * With the opengl renderer:
+ *
  * ```
  * "SDL.texture.opengl.texture" (number) - the GLuint texture associated with the texture
  * "SDL.texture.opengl.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture
@@ -446,6 +450,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  * ```
  *
  * With the opengles2 renderer:
+ *
  * ```
  * "SDL.texture.opengles2.texture" (number) - the GLuint texture associated with the texture
  * "SDL.texture.opengles2.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture

include/SDL3/SDL_video.h

@@ -868,28 +868,33 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *tit
 extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, Uint32 flags);
 
 /**
- * Create an SDL window from properties representing an existing native window.
+ * Create an SDL window from properties representing an existing native
+ * window.
  *
  * These are the supported properties:
  *
  * On macOS:
+ *
  * ```
  * "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window
  * "cocoa.view" (pointer) - optional, the (__unsafe_unretained) NSView associated with the window, defaults to [window contentView]
  * ```
  *
  * On Windows:
+ *
  * ```
  * "win32.hwnd" (pointer) - the HWND associated with the window
  * "win32.pixel_format_hwnd" (pointer) - optional, another window to share pixel format with, useful for OpenGL windows
  * ```
  *
  * On X11:
+ *
  * ```
  * "x11.window" (number) - the X11 Window associated with the window
  * ```
  *
  * On all platforms:
+ *
  * ```
  * "opengl" (boolean) - optional, true if the window will be used with OpenGL rendering
  * "vulkan" (boolean) - optional, true if the window will be used with Vulkan rendering
@@ -957,18 +962,21 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * The following properties are provided by SDL:
  *
  * On Android:
+ *
  * ```
  * "SDL.window.android.window" (pointer) - the ANativeWindow associated with the window
  * "SDL.window.android.surface" (pointer) - the EGLSurface associated with the window
  * ```
  *
  * On iOS:
+ *
  * ```
  * "SDL.window.uikit.window" (pointer) - the (__unsafe_unretained) UIWindow associated with the window
  * "SDL.window.uikit.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window
  * ```
  *
  * On KMS/DRM:
+ *
  * ```
  * "SDL.window.kmsdrm.dev_index" (number) - the device index associated with the window (e.g. the X in /dev/dri/cardX)
  * "SDL.window.kmsdrm.drm_fd" (number) - the DRM FD associated with the window
@@ -976,12 +984,14 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * ```
  *
  * On macOS:
+ *
  * ```
  * "SDL.window.cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window
  * "SDL.window.cocoa.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window
  * ```
  *
  * On Vivante:
+ *
  * ```
  * "SDL.window.vivante.display" (pointer) - the EGLNativeDisplayType associated with the window
  * "SDL.window.vivante.window" (pointer) - the EGLNativeWindowType associated with the window
@@ -989,11 +999,13 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * ```
  *
  * On UWP:
+ *
  * ```
  * "SDL.window.winrt.window" (pointer) - the IInspectable CoreWindow associated with the window
  * ```
  *
  * On Windows:
+ *
  * ```
  * "SDL.window.win32.hwnd" (pointer) - the HWND associated with the window
  * "SDL.window.win32.hdc" (pointer) - the HDC associated with the window
@@ -1001,6 +1013,7 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * ```
  *
  * On Wayland:
+ *
  * ```
  * "SDL.window.wayland.registry" (pointer) - the wl_registry associated with the window
  * "SDL.window.wayland.display" (pointer) - the wl_display associated with the window
@@ -1012,10 +1025,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * "SDL.window.wayland.xdg_positioner" (pointer) - the xdg_positioner associated with the window, in popup mode
  * ```
  *
- * Note: The xdg_* window objects do not internally persist across window show/hide calls.
- *       They will be null if the window is hidden and must be queried each time it is shown.
+ * Note: The xdg_* window objects do not internally persist across window
+ * show/hide calls. They will be null if the window is hidden and must be
+ * queried each time it is shown.
  *
  * On X11:
+ *
  * ```
  * "SDL.window.x11.display" (pointer) - the X11 Display associated with the window
  * "SDL.window.x11.screen" (number) - the screen number associated with the window