From db6b6bd75ef5fb1335d192cb4edc11719967f52e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Tue, 16 Apr 2024 13:29:26 -0400
Subject: [PATCH] include: Fixed up some sensor documentation.

Fixes #9468.
---
 include/SDL3/SDL_sensor.h | 71 +++++++++++++++++++++------------------
 1 file changed, 39 insertions(+), 32 deletions(-)

diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index 652d93cced561..4d8b1ccb5f297 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -63,35 +63,35 @@ typedef struct SDL_Sensor SDL_Sensor;
 typedef Uint32 SDL_SensorID;
 
 /**
- * The different sensors defined by SDL
+ * A constant to represent standard gravity for accelerometer sensors.
  *
- * Additional sensors may be available, using platform dependent semantics.
+ * The accelerometer returns the current acceleration in SI meters per second
+ * squared. This measurement includes the force of gravity, so a device at
+ * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
+ * earth, which is a positive Y value.
  *
- * Hare are the additional Android sensors:
- * https://developer.android.com/reference/android/hardware/SensorEvent.html#values
+ * \since This macro is available since SDL 3.0.0.
  */
-typedef enum SDL_SensorType
-{
-    SDL_SENSOR_INVALID = -1,    /**< Returned for an invalid sensor */
-    SDL_SENSOR_UNKNOWN,         /**< Unknown sensor type */
-    SDL_SENSOR_ACCEL,           /**< Accelerometer */
-    SDL_SENSOR_GYRO,            /**< Gyroscope */
-    SDL_SENSOR_ACCEL_L,         /**< Accelerometer for left Joy-Con controller and Wii nunchuk */
-    SDL_SENSOR_GYRO_L,          /**< Gyroscope for left Joy-Con controller */
-    SDL_SENSOR_ACCEL_R,         /**< Accelerometer for right Joy-Con controller */
-    SDL_SENSOR_GYRO_R           /**< Gyroscope for right Joy-Con controller */
-} SDL_SensorType;
+#define SDL_STANDARD_GRAVITY    9.80665f
 
 /**
- * Accelerometer sensor.
+ * The different sensors defined by SDL.
+ *
+ * Additional sensors may be available, using platform dependent semantics.
+ *
+ * Hare are the additional Android sensors:
+ * https://developer.android.com/reference/android/hardware/SensorEvent.html#values
+ *
+ * Accelerometer sensor notes:
  *
  * The accelerometer returns the current acceleration in SI meters per second
  * squared. This measurement includes the force of gravity, so a device at
  * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
  * earth, which is a positive Y value.
  *
- * values[0]: Acceleration on the x axis values[1]: Acceleration on the y axis
- * values[2]: Acceleration on the z axis
+ * - `values[0]`: Acceleration on the x axis
+ * - `values[1]`: Acceleration on the y axis
+ * - `values[2]`: Acceleration on the z axis
  *
  * For phones and tablets held in natural orientation and game controllers
  * held in front of you, the axes are defined as follows:
@@ -100,16 +100,9 @@ typedef enum SDL_SensorType
  * - -Y ... +Y : bottom ... top
  * - -Z ... +Z : farther ... closer
  *
- * The axis data is not changed when the device is rotated.
- *
- * \since This macro is available since SDL 3.0.0.
+ * The accelerometer axis data is not changed when the device is rotated.
  *
- * \sa SDL_GetCurrentDisplayOrientation
- */
-#define SDL_STANDARD_GRAVITY    9.80665f
-
-/**
- * Gyroscope sensor.
+ * Gyroscope sensor notes:
  *
  * The gyroscope returns the current rate of rotation in radians per second.
  * The rotation is positive in the counter-clockwise direction. That is,
@@ -117,9 +110,9 @@ typedef enum SDL_SensorType
  * see positive rotation on that axis when it appeared to be rotating
  * counter-clockwise.
  *
- * values[0]: Angular speed around the x axis (pitch)
- * values[1]: Angular speed around the y axis (yaw)
- * values[2]: Angular speed around the z axis (roll)
+ * - `values[0]`: Angular speed around the x axis (pitch)
+ * - `values[1]`: Angular speed around the y axis (yaw)
+ * - `values[2]`: Angular speed around the z axis (roll)
  *
  * For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:
  *
@@ -127,10 +120,24 @@ typedef enum SDL_SensorType
  * - -Y ... +Y : bottom ... top
  * - -Z ... +Z : farther ... closer
  *
- * The axis data is not changed when the device is rotated.
+ * The gyroscope axis data is not changed when the device is rotated.
  *
- * \sa SDL_GetCurrentDisplayOrientation()
+ * \since This enum is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetCurrentDisplayOrientation
  */
+typedef enum SDL_SensorType
+{
+    SDL_SENSOR_INVALID = -1,    /**< Returned for an invalid sensor */
+    SDL_SENSOR_UNKNOWN,         /**< Unknown sensor type */
+    SDL_SENSOR_ACCEL,           /**< Accelerometer */
+    SDL_SENSOR_GYRO,            /**< Gyroscope */
+    SDL_SENSOR_ACCEL_L,         /**< Accelerometer for left Joy-Con controller and Wii nunchuk */
+    SDL_SENSOR_GYRO_L,          /**< Gyroscope for left Joy-Con controller */
+    SDL_SENSOR_ACCEL_R,         /**< Accelerometer for right Joy-Con controller */
+    SDL_SENSOR_GYRO_R           /**< Gyroscope for right Joy-Con controller */
+} SDL_SensorType;
+
 
 /* Function prototypes */