Sync SDL3 wiki -> header

[ci skip]

include/SDL3/SDL_events.h

@@ -771,9 +771,10 @@ typedef struct SDL_CameraDeviceEvent
 /**
  * Notification dialog event structure (event.notification.*)
  *
- * An `action_id` value of 'default' for an SDL_EVENT_NOTIFICATION_ACTION_INVOKED
- * event indicates that the notification was interacted with without selecting a
- * specific action (e.g. the body of the notification was clicked on).
+ * An `action_id` value of 'default' for an
+ * SDL_EVENT_NOTIFICATION_ACTION_INVOKED event indicates that the notification
+ * was interacted with without selecting a specific action (e.g. the body of
+ * the notification was clicked on).
  *
  * \since This struct is available since SDL 3.6.0.
  */

include/SDL3/SDL_notification.h

@@ -60,19 +60,20 @@ extern "C" {
 #endif
 
 /**
- * The path to an image to be used as the header icon for system notifications on
- * some platforms. This is required on:
- *  - Windows
- *  - *nix when not running in a container, and no .desktop entry is available
+ * The path to an image to be used as the header icon for system notifications
+ * on some platforms.
  *
- * Image types supported depend on the platform, but .png generally offers the best
- * compatability.
+ * This is required on: - Windows - *nix when not running in a container, and
+ * no .desktop entry is available
  *
- * On *nix platforms, this can also be the name of a system icon, as specified by
- * the Icon Naming Specification.
+ * Image types supported depend on the platform, but .png generally offers the
+ * best compatability.
  *
- * Can be set before calling SDL_ShowNotification() or SDL_ShowSimpleNotification()
- * for the first time.
+ * On *nix platforms, this can also be the name of a system icon, as specified
+ * by the Icon Naming Specification.
+ *
+ * Can be set before calling SDL_ShowNotification() or
+ * SDL_ShowSimpleNotification() for the first time.
  *
  * \since This macro is available since SDL 3.6.0.
  */
@@ -95,14 +96,15 @@ typedef enum SDL_NotificationActionType
 
 /**
  * Notification structure describing actions that can be used to allow users
- * to interact with notification dialogs. Exactly How they are presented depends
- * on the platform and implementation.
+ * to interact with notification dialogs.
+ *
+ * Exactly How they are presented depends on the platform and implementation.
  *
  * User interactions with a notification are reported via events with the type
  * SDL_EVENT_NOTIFICATION_ACTION_INVOKED.
  *
- * Action types:
- * - button: A button with a localized text label, which generates feedback when activated.
+ * Action types: - button: A button with a localized text label, which
+ * generates feedback when activated.
  *
  * \sa SDL_NotificationEvent
  * \sa SDL_NotificationActionType
@@ -132,116 +134,123 @@ typedef union SDL_NotificationAction
 #define SDL_PROP_NOTIFICATION_TITLE_STRING        "SDL.notification.title"
 
 /**
- *  Requests permission from the system to display notifications. A return value of `true`
- *  only means that the system supports notifications, and that the request for permission
- *  was successfully issued. It does not reflect any user settings to allow or deny
- *  notifications.
+ * Requests permission from the system to display notifications.
+ *
+ * A return value of `true` only means that the system supports notifications,
+ * and that the request for permission was successfully issued. It does not
+ * reflect any user settings to allow or deny notifications.
  *
- *  \returns True on success or false on failure; call
- *           SDL_GetError() for more information.
+ * \returns True on success or false on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \since This function is available since SDL 3.6.0
+ * \since This function is available since SDL 3.6.0.
  *
- *  \sa SDL_ShowNotification
- *  \sa SDL_ShowNotificationWithProperties
- *  \sa SDL_NotificationAction
+ * \sa SDL_ShowNotification
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_NotificationAction
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_RequestNotificationPermission(void);
 
 /**
- *  Show a system notification.
+ * Show a system notification.
  *
- *  System notifications are small, asynchronous popup windows that notify the user
- *  of some information. How they are displayed is system dependent.
+ * System notifications are small, asynchronous popup windows that notify the
+ * user of some information. How they are displayed is system dependent.
  *
- *  These are the supported properties:
+ * These are the supported properties:
  *
  * - `SDL_PROP_NOTIFICATION_TITLE_STRING`: the title of the notification, in
  *   UTF-8 encoding. This property is required.
- * - `SDL_PROP_NOTIFICATION_ACTIONS_POINTER`: An array of pointers to `SDL_NotificationAction`
- *   structs that will add actions to the notification, usually in the form of buttons or menu
- *   items. Note that systems may have a limit on the maximum number of actions that a
+ * - `SDL_PROP_NOTIFICATION_ACTIONS_POINTER`: An array of pointers to
+ *   `SDL_NotificationAction` structs that will add actions to the
+ *   notification, usually in the form of buttons or menu items. Note that
+ *   systems may have a limit on the maximum number of actions that a
  *   notification can have.
- * - `SDL_PROP_NOTIFICATIONS_ACTION_COUNT_NUMBER`: the number of actions in the array of actions,
- *   if it exists.
- * - `SDL_PROP_NOTIFICATION_IMAGE_POINTER`: a pointer to an `SDL_Surface` containing
- *   an image that will be attached to the notification. In most cases, the image is displayed
- *   in the form of a large icon or thumbnail alongside the message body. Notifications on Apple
- *   platforms can be expanded to show a larger format image.
- * - `SDL_PROP_NOTIFICATION_MESSAGE_STRING`: the message body of the notification,
- *   in UTF-8 encoding.
- * - `SDL_PROP_NOTIFICATION_PRIORITY_NUMBER`: an `SDL_NotificationPriority` value representing
- *   the notification priority.
- * - `SDL_PROP_NOTIFICATION_REPLACES_NUMBER`: the `SDL_NotificationID` of a previously
- *   shown notification that this notification should replace.
- * - `SDL_PROP_NOTIFICATION_SOUND_STRING`: sets a sound to play when the notification is shown.
- *   This can have the value "default", to play the system default notification sound, "silent",
- *   to play no sound, or contain the path to a file with a custom sound. The paths and formats
- *   that can be used for custom sounds are system-specific, and can have some restrictions,
- *   depending on the platform:
- *    - Apple platforms require that the sound file is contained within the app bundle. Supported
- *      formats are: Linear PCM, MA4 (IMA/ADPCM), uLaw, or aLaw, in an .aiff, .wav, or .caf file.
- *    - Windows can only play custom notification sounds when the app is packaged inside an MSIX
- *      installer. Playback from arbitrary file paths is not supported. Supported formats are:
- *      .aac, .flac, .m4a, .mp3, .wav, and .wma.
- *    - Unix platforms can generally load sounds from any arbitrary path, as long as the read
- *      permissions are correct. Supported formats are: ogg/opus, ogg/vorbis, and wav/pcm.
- *    If this property is not set, the system default sound will be used.
- * - `SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN`: true if the notification should not persist
- *   in the system notification center after initially being shown.
+ * - `SDL_PROP_NOTIFICATIONS_ACTION_COUNT_NUMBER`: the number of actions in
+ *   the array of actions, if it exists.
+ * - `SDL_PROP_NOTIFICATION_IMAGE_POINTER`: a pointer to an `SDL_Surface`
+ *   containing an image that will be attached to the notification. In most
+ *   cases, the image is displayed in the form of a large icon or thumbnail
+ *   alongside the message body. Notifications on Apple platforms can be
+ *   expanded to show a larger format image.
+ * - `SDL_PROP_NOTIFICATION_MESSAGE_STRING`: the message body of the
+ *   notification, in UTF-8 encoding.
+ * - `SDL_PROP_NOTIFICATION_PRIORITY_NUMBER`: an `SDL_NotificationPriority`
+ *   value representing the notification priority.
+ * - `SDL_PROP_NOTIFICATION_REPLACES_NUMBER`: the `SDL_NotificationID` of a
+ *   previously shown notification that this notification should replace.
+ * - `SDL_PROP_NOTIFICATION_SOUND_STRING`: sets a sound to play when the
+ *   notification is shown. This can have the value "default", to play the
+ *   system default notification sound, "silent", to play no sound, or contain
+ *   the path to a file with a custom sound. The paths and formats that can be
+ *   used for custom sounds are system-specific, and can have some
+ *   restrictions, depending on the platform:
+ * - Apple platforms require that the sound file is contained within the app
+ *   bundle. Supported formats are: Linear PCM, MA4 (IMA/ADPCM), uLaw, or
+ *   aLaw, in an .aiff, .wav, or .caf file.
+ * - Windows can only play custom notification sounds when the app is packaged
+ *   inside an MSIX installer. Playback from arbitrary file paths is not
+ *   supported. Supported formats are: .aac, .flac, .m4a, .mp3, .wav, and
+ *   .wma.
+ * - Unix platforms can generally load sounds from any arbitrary path, as long
+ *   as the read permissions are correct. Supported formats are: ogg/opus,
+ *   ogg/vorbis, and wav/pcm. If this property is not set, the system default
+ *   sound will be used.
+ * - `SDL_PROP_NOTIFICATION_TRANSIENT_BOOLEAN`: true if the notification
+ *   should not persist in the system notification center after initially
+ *   being shown.
  *
  * Not all properties are supported by all platforms.
  *
- * Notifications are available on:
- *  - Windows 10 or higher
- *  - macOS 10.14 or higher
- *  - iOS 11 or higher
- *  - *nix platforms that support the org.freedesktop.Notifications, or
- *    org.freedesktop.portal.Notification interfaces
+ * Notifications are available on: - Windows 10 or higher - macOS 10.14 or
+ * higher - iOS 11 or higher - *nix platforms that support the
+ * org.freedesktop.Notifications, or org.freedesktop.portal.Notification
+ * interfaces
  *
- *  \param props the properties to be used when creating this notification.
- *  \returns A non-zero SDL_NotificationID on success or 0 on failure; call
- *           SDL_GetError() for more information.
+ * \param props the properties to be used when creating this notification.
+ * \returns A non-zero SDL_NotificationID on success or 0 on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \since This function is available since SDL 3.6.0
+ * \since This function is available since SDL 3.6.0.
  *
- *  \sa SDL_ShowNotification
- *  \sa SDL_NotificationAction
- *  \sa SDL_NotificationPriority
- *  \sa SDL_NotificationEvent
+ * \sa SDL_ShowNotification
+ * \sa SDL_NotificationAction
+ * \sa SDL_NotificationPriority
+ * \sa SDL_NotificationEvent
  */
 extern SDL_DECLSPEC SDL_NotificationID SDLCALL SDL_ShowNotificationWithProperties(SDL_PropertiesID props);
 
 /**
- *  Show a system notification with normal priority.
+ * Show a system notification with normal priority.
  *
- *  \param title    UTF-8 title text, required.
- *  \param message  UTF-8 message text, may be NULL.
- *  \param image The image associated with this notification, may be NULL.
- *  \param actions An array of actions to attach to the notification, may be NULL.
- *  \param num_actions The number of actions in the actions array.
- *  \returns A non-zero SDL_NotificationID on success or 0 on failure; call
- *           SDL_GetError() for more information.
+ * \param title UTF-8 title text, required.
+ * \param message UTF-8 message text, may be NULL.
+ * \param image The image associated with this notification, may be NULL.
+ * \param actions An array of actions to attach to the notification, may be
+ *                NULL.
+ * \param num_actions The number of actions in the actions array.
+ * \returns A non-zero SDL_NotificationID on success or 0 on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \since This function is available since SDL 3.6.0
+ * \since This function is available since SDL 3.6.0.
  *
- *  \sa SDL_ShowNotificationWithProperties
- *  \sa SDL_NotificationAction
- *  \sa SDL_NotificationEvent
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_NotificationAction
+ * \sa SDL_NotificationEvent
  */
 extern SDL_DECLSPEC SDL_NotificationID SDLCALL SDL_ShowNotification(const char *title, const char *message, SDL_Surface *image, SDL_NotificationAction *actions, int num_actions);
 
 /**
- *  Remove a notification.
+ * Remove a notification.
  *
- *  \param notification the ID of the notification to remove.
- *  \returns True on success or false on failure; call
- *           SDL_GetError() for more information.
+ * \param notification the ID of the notification to remove.
+ * \returns True on success or false on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \since This function is available since SDL 3.6.0
+ * \since This function is available since SDL 3.6.0.
  *
- *  \sa SDL_ShowNotificationWithProperties
- *  \sa SDL_ShowNotification
+ * \sa SDL_ShowNotificationWithProperties
+ * \sa SDL_ShowNotification
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_RemoveNotification(SDL_NotificationID notification);