Sync SDL3 wiki -> header

[ci skip]

include/SDL3/SDL_camera.h

@@ -31,22 +31,22 @@
  *
  * Several platforms will alert the user if an app tries to access a camera,
  * and some will present a UI asking the user if your application should be
- * allowed to obtain images at all, which they can deny. A successfully
+ * allowed to obtain images at all, which they can deny. A successfully opened
- * opened camera will not provide images until permission is granted.
+ * camera will not provide images until permission is granted. Applications,
- * Applications, after opening a camera device, can see if they were granted
+ * after opening a camera device, can see if they were granted access by
- * access by either polling with the SDL_GetCameraPermissionState() function,
+ * either polling with the SDL_GetCameraPermissionState() function, or waiting
- * or waiting for an SDL_EVENT_CAMERA_DEVICE_APPROVED or
+ * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED
- * SDL_EVENT_CAMERA_DEVICE_DENIED event. Platforms that don't have any
+ * event. Platforms that don't have any user approval process will report
- * user approval process will report approval immediately.
+ * approval immediately.
  *
  * Note that SDL cameras only provide video as individual frames; they will
  * not provide full-motion video encoded in a movie file format, although an
- * app is free to encode the acquired frames into any format it likes. It
+ * app is free to encode the acquired frames into any format it likes. It also
- * also does not provide audio from the camera hardware through this API;
+ * does not provide audio from the camera hardware through this API; not only
- * not only do many webcams not have microphones at all, many people--from
+ * do many webcams not have microphones at all, many people--from streamers to
- * streamers to people on Zoom calls--will want to use a separate microphone
+ * people on Zoom calls--will want to use a separate microphone regardless of
- * regardless of the camera. In any case, recorded audio will be available
+ * the camera. In any case, recorded audio will be available through SDL's
- * through SDL's audio API no matter what hardware provides the microphone.
+ * audio API no matter what hardware provides the microphone.
  *
  * ## Camera gotchas
  *

include/SDL3/SDL_clipboard.h

@@ -29,19 +29,18 @@
  *
  * ## Basic use (text)
  *
- * Obtaining and publishing simple text to the system clipboard is as easy
+ * Obtaining and publishing simple text to the system clipboard is as easy as
- * as calling SDL_GetClipboardText() and SDL_SetClipboardText(),
+ * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively.
- * respectively. These deal with C strings in UTF-8 encoding. Data
+ * These deal with C strings in UTF-8 encoding. Data transmission and encoding
- * transmission and encoding conversion is completely managed by SDL.
+ * conversion is completely managed by SDL.
  *
  * ## Clipboard callbacks (data other than text)
  *
  * Things get more complicated when the clipboard contains something other
- * than text. Not only can the system clipboard contain data of any type,
+ * than text. Not only can the system clipboard contain data of any type, in
- * in some cases it can contain the same data in different formats! For
+ * some cases it can contain the same data in different formats! For example,
- * example, an image painting app might let the user copy a graphic to the
+ * an image painting app might let the user copy a graphic to the clipboard,
- * clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to
+ * and offers it in .BMP, .JPG, or .PNG format for other apps to consume.
- * consume.
  *
  * Obtaining clipboard data ("pasting") like this is a matter of calling
  * SDL_GetClipboardData() and telling it the mimetype of the data you want.
@@ -56,9 +55,9 @@
  * rather the mimetypes it is willing to provide and a callback function.
  * During the callback, the app will generate the data. This allows massive
  * data sets to be provided to the clipboard, without any data being copied
- * before it is explicitly requested. More specifically, it allows an app
+ * before it is explicitly requested. More specifically, it allows an app to
- * to offer data in multiple formats without providing a copy of all of
+ * offer data in multiple formats without providing a copy of all of them
- * them upfront. If the app has an image that it could provide in PNG or JPG
+ * upfront. If the app has an image that it could provide in PNG or JPG
  * format, it doesn't have to encode it to either of those unless and until
  * something tries to paste it.
  *
@@ -67,11 +66,11 @@
  * The X11 and Wayland video targets have a concept of the "primary selection"
  * in addition to the usual clipboard. This is generally highlighted (but not
  * explicitly copied) text from various apps. SDL offers APIs for this through
- * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText().
+ * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers
- * SDL offers these APIs on platforms without this concept, too, but only so
+ * these APIs on platforms without this concept, too, but only so far that it
- * far that it will keep a copy of a string that the app sets for later
+ * will keep a copy of a string that the app sets for later retrieval; the
- * retrieval; the operating system will not ever attempt to change the
+ * operating system will not ever attempt to change the string externally if
- * string externally if it doesn't support a primary selection.
+ * it doesn't support a primary selection.
  */
 
 #ifndef SDL_clipboard_h_

include/SDL3/SDL_cpuinfo.h

@@ -33,7 +33,8 @@
  * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are
  * available on all platforms, even if they don't make sense (an ARM processor
  * will never have SSE and an x86 processor will never have NEON, for example,
- * but these functions still exist and will simply return false in these cases).
+ * but these functions still exist and will simply return false in these
+ * cases).
  */
 
 #ifndef SDL_cpuinfo_h_

include/SDL3/SDL_endian.h

@@ -28,13 +28,14 @@
  * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's
  * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE,
  * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the
- * latter case, the functionality is provided by macros that become no-ops
+ * latter case, the functionality is provided by macros that become no-ops if
- * if a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
+ * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
  * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC
  * processor (bigendian), the macros behavior is reversed.
  *
  * The swap routines are inline functions, and attempt to use compiler
- * intrinsics, inline assembly, and other magic to make byteswapping efficient.
+ * intrinsics, inline assembly, and other magic to make byteswapping
+ * efficient.
  */
 
 #ifndef SDL_endian_h_

include/SDL3/SDL_events.h

@@ -25,9 +25,9 @@
  * Event queue management.
  *
  * It's extremely common--often required--that an app deal with SDL's event
- * queue. Almost all useful information about interactions with the real
+ * queue. Almost all useful information about interactions with the real world
- * world flow through here: the user interacting with the computer and app,
+ * flow through here: the user interacting with the computer and app, hardware
- * hardware coming and going, the system changing in some way, etc.
+ * coming and going, the system changing in some way, etc.
  *
  * An app generally takes a moment, perhaps at the start of a new frame, to
  * examine any events that have occured since the last time and process or
@@ -43,10 +43,10 @@
  * beneficial for certain types of programs on low-power hardware. One may
  * also call SDL_AddEventWatch() to set a callback when new events arrive.
  *
- * The app is free to generate their own events, too: SDL_PushEvent allows
+ * The app is free to generate their own events, too: SDL_PushEvent allows the
- * the app to put events onto the queue for later retrieval;
+ * app to put events onto the queue for later retrieval; SDL_RegisterEvents
- * SDL_RegisterEvents can guarantee that these events have a type that isn't
+ * can guarantee that these events have a type that isn't in use by other
- * in use by other parts of the system.
+ * parts of the system.
  */
 
 #ifndef SDL_events_h_

include/SDL3/SDL_joystick.h

@@ -25,8 +25,8 @@
  * SDL joystick support.
  *
  * This is the lower-level joystick handling. If you want the simpler option,
- * where what each button does is well-defined, you should use the gamepad
+ * where what each button does is well-defined, you should use the gamepad API
- * API instead.
+ * instead.
  *
  * The term "instance_id" is the current instantiation of a joystick device in
  * the system, if the joystick is removed and then re-inserted then it will

include/SDL3/SDL_keycode.h

@@ -24,8 +24,8 @@
  *
  * Defines constants which identify keyboard keys and modifiers.
  *
- * Please refer to the Best Keyboard Practices document for
+ * Please refer to the Best Keyboard Practices document for details on what
- * details on what this information means and how best to use it.
+ * this information means and how best to use it.
  *
  * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
  */

include/SDL3/SDL_loadso.h

@@ -49,8 +49,8 @@
  * - Once a library is unloaded, all pointers into it obtained through
  *   SDL_LoadFunction() become invalid, even if the library is later reloaded.
  *   Don't unload a library if you plan to use these pointers in the future.
- *   Notably: beware of giving one of these pointers to atexit(), since it
+ *   Notably: beware of giving one of these pointers to atexit(), since it may
- *   may call that pointer after the library unloads.
+ *   call that pointer after the library unloads.
  */
 
 #ifndef SDL_loadso_h_

include/SDL3/SDL_main.h

@@ -35,12 +35,12 @@
  *
  * SDL will take care of platform specific details on how it gets called.
  *
- * This is also where an app can be configured to use the main callbacks,
+ * This is also where an app can be configured to use the main callbacks, via
- * via the SDL_MAIN_USE_CALLBACKS macro.
+ * the SDL_MAIN_USE_CALLBACKS macro.
  *
  * This is a "single-header library," which is to say that including this
- * header inserts code into your program, and you should only include it
+ * header inserts code into your program, and you should only include it once
- * once in most cases. SDL.h does not include this header automatically.
+ * in most cases. SDL.h does not include this header automatically.
  *
  * For more information, see:
  *

include/SDL3/SDL_scancode.h

@@ -24,8 +24,8 @@
  *
  * Defines keyboard scancodes.
  *
- * Please refer to the Best Keyboard Practices document for
+ * Please refer to the Best Keyboard Practices document for details on what
- * details on what this information means and how best to use it.
+ * this information means and how best to use it.
  *
  * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
  */