Sync SDL3 wiki -> header

include/SDL3/SDL_events.h

@@ -719,10 +719,10 @@ typedef struct SDL_TouchFingerEvent
  * Pressure-sensitive pen proximity event structure (event.pmotion.*)
  *
  * When a pen becomes visible to the system (it is close enough to a tablet,
- * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new
+ * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's
- * pen's ID. This ID is valid until the pen leaves proximity again (has
+ * ID. This ID is valid until the pen leaves proximity again (has been removed
- * been removed from the tablet's area, the tablet has been unplugged, etc).
+ * from the tablet's area, the tablet has been unplugged, etc). If the same
- * If the same pen reenters proximity again, it will be given a new ID.
+ * pen reenters proximity again, it will be given a new ID.
  *
  * Note that "proximity" means "close enough for the tablet to know the tool
  * is there." The pen touching and lifting off from the tablet while not
@@ -742,11 +742,11 @@ typedef struct SDL_PenProximityEvent
 /**
  * Pressure-sensitive pen motion event structure (event.pmotion.*)
  *
- * Depending on the hardware, you may get motion events when the
+ * Depending on the hardware, you may get motion events when the pen is not
- * pen is not touching a tablet, for tracking a pen even when it
+ * touching a tablet, for tracking a pen even when it isn't drawing. You
- * isn't drawing. You should listen for SDL_EVENT_PEN_DOWN and
+ * should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check
- * SDL_EVENT_PEN_UP events, or check `pen_state & SDL_PEN_INPUT_DOWN`
+ * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when
- * to decide if a pen is "drawing" when dealing with pen motion.
+ * dealing with pen motion.
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -765,8 +765,8 @@ typedef struct SDL_PenMotionEvent
 /**
  * Pressure-sensitive pen touched event structure (event.ptouch.*)
  *
- * These events come when a pen touches a surface (a tablet, etc),
+ * These events come when a pen touches a surface (a tablet, etc), or lifts
- * or lifts off from one.
+ * off from one.
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -787,9 +787,8 @@ typedef struct SDL_PenTouchEvent
 /**
  * Pressure-sensitive pen button event structure (event.pbutton.*)
  *
- * This is for buttons on the pen itself that the user might click.
+ * This is for buttons on the pen itself that the user might click. The pen
- * The pen itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN
+ * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead.
- * event instead.
  *
  * \since This struct is available since SDL 3.0.0.
  */
@@ -808,10 +807,10 @@ typedef struct SDL_PenButtonEvent
 } SDL_PenButtonEvent;
 
 /**
- * Pressure-sensitive pen pressure / angle event structure
+ * Pressure-sensitive pen pressure / angle event structure (event.paxis.*)
- * (event.paxis.*)
  *
- * You might get some of these events even if the pen isn't touching the tablet.
+ * You might get some of these events even if the pen isn't touching the
+ * tablet.
  *
  * \since This struct is available since SDL 3.0.0.
  */

include/SDL3/SDL_pen.h

@@ -24,9 +24,9 @@
  *
  * SDL pen event handling.
  *
- * SDL provides an API for pressure-sensitive pen (stylus and/or
+ * SDL provides an API for pressure-sensitive pen (stylus and/or eraser)
- * eraser) handling, e.g., for input and drawing tablets or suitably equipped
+ * handling, e.g., for input and drawing tablets or suitably equipped mobile /
- * mobile / tablet devices.
+ * tablet devices.
  *
  * To get started with pens, simply handle SDL_EVENT_PEN_* events. When a pen
  * starts providing input, SDL will assign it a unique SDL_PenID, which will
@@ -52,8 +52,8 @@ extern "C" {
  * Zero is used to signify an invalid/null device.
  *
  * These show up in pen events when SDL sees input from them. They remain
- * consistent as long as SDL can recognize a tool to be the same pen; but if
+ * consistent as long as SDL can recognize a tool to be the same pen; but if a
- * a pen physically leaves the area and returns, it might get a new ID.
+ * pen physically leaves the area and returns, it might get a new ID.
  *
  * \since This datatype is available since SDL 3.0.0.
  */
@@ -77,10 +77,10 @@ typedef Uint32 SDL_PenInputFlags;
 /**
  * Pen axis indices.
  *
- * These are the valid values for the `axis` field in SDL_PenAxisEvent.
+ * These are the valid values for the `axis` field in SDL_PenAxisEvent. All
- * All axes are either normalised to 0..1 or report a (positive or negative) angle
+ * axes are either normalised to 0..1 or report a (positive or negative) angle
- * in degrees, with 0.0 representing the centre. Not all pens/backends support all
+ * in degrees, with 0.0 representing the centre. Not all pens/backends support
- * axes: unsupported axes are always zero.
+ * all axes: unsupported axes are always zero.
  *
  * To convert angles for tilt and rotation into vector representation, use
  * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example: