docs(sensor_plus): improve description of accelerometer (#1425)

Co-authored-by: Joachim Nohl <43643339+nohli@users.noreply.github.com>

docs/sensors_plus/usage.mdx

@@ -11,12 +11,23 @@ file](https://plus.fluttercommunity.dev/docs/overview).
 
 This will expose such classes of sensor events through a set of streams:
 
-- `AccelerometerEvent` describes the velocity of the device, including the
-  effects of gravity. Put simply, you can use accelerometer readings to tell if
-  the device is moving in a particular direction.
-- `UserAccelerometerEvent` also describes the velocity of the device, but don't
-  include gravity. They can also be thought of as just the user's affect on the
-  device.
+- `UserAccelerometerEvent` describes the acceleration of the device, in m/s<sup>2</sup>.
+  If the device is still, or is moving along a straight line at constant speed,
+  the reported acceleration is zero.
+  If the device is moving e.g. towards north and its speed is increasing, the reported acceleration
+  is towards north; if it is slowing down, the reported acceleration is towards south;
+  if it is turning right, the reported acceleration is towards east.
+  The data of this stream is obtained by filtering out the effect of gravity from `AccelerometerEvent`.
+- `AccelerometerEvent` describes the acceleration of the device, in m/s<sup>2</sup>, including the
+  effects of gravity. Unlike `UserAccelerometerEvent`, this stream reports raw data from
+  the accelerometer (physical sensor embedded in the mobile device) without any post-processing.
+  The accelerometer is unable to distinguish between the effect of an accelerated movement of the
+  device and the effect of the surrounding gravitational field.
+  This means that, at the surface of Earth, even if the device is completely still,
+  the reading of `AccelerometerEvent` is an acceleration of intensity 9.8 directed upwards
+  (the opposite of the graviational acceleration).
+  This can be used to infer information about the position of the device (horizontal/vertical/tilted).
+  `AccelerometerEvent` reports zero acceleration if the device is free falling.
 - `GyroscopeEvent` describes the rotation of the device.
 - `MagnetometerEvent` describes the ambient magnetic field surrounding the
   device. A compass is an example usage of this data.
@@ -30,15 +41,15 @@ respectively.
 ```dart
 import 'package:sensors_plus/sensors_plus.dart';
 
-accelerometerEvents.listen((AccelerometerEvent event) {
+userAccelerometerEvents.listen((UserAccelerometerEvent event) {
   print(event);
 });
-// [AccelerometerEvent (x: 0.0, y: 9.8, z: 0.0)]
+// [UserAccelerometerEvent (x: 0.0, y: 0.0, z: 0.0)]
 
-userAccelerometerEvents.listen((UserAccelerometerEvent event) {
+accelerometerEvents.listen((AccelerometerEvent event) {
   print(event);
 });
-// [UserAccelerometerEvent (x: 0.0, y: 0.0, z: 0.0)]
+// [AccelerometerEvent (x: 0.0, y: 9.8, z: 0.0)]
 
 gyroscopeEvents.listen((GyroscopeEvent event) {
   print(event);

packages/sensors_plus/sensors_plus/example/lib/main.dart

@@ -44,21 +44,21 @@ class _MyHomePageState extends State<MyHomePage> {
   static const int _snakeColumns = 20;
   static const double _snakeCellSize = 10.0;
 
-  List<double>? _accelerometerValues;
   List<double>? _userAccelerometerValues;
+  List<double>? _accelerometerValues;
   List<double>? _gyroscopeValues;
   List<double>? _magnetometerValues;
   final _streamSubscriptions = <StreamSubscription<dynamic>>[];
 
   @override
   Widget build(BuildContext context) {
+    final userAccelerometer = _userAccelerometerValues
+        ?.map((double v) => v.toStringAsFixed(1))
+        .toList();
     final accelerometer =
         _accelerometerValues?.map((double v) => v.toStringAsFixed(1)).toList();
     final gyroscope =
         _gyroscopeValues?.map((double v) => v.toStringAsFixed(1)).toList();
-    final userAccelerometer = _userAccelerometerValues
-        ?.map((double v) => v.toStringAsFixed(1))
-        .toList();
     final magnetometer =
         _magnetometerValues?.map((double v) => v.toStringAsFixed(1)).toList();
 
@@ -90,7 +90,7 @@ class _MyHomePageState extends State<MyHomePage> {
             child: Row(
               mainAxisAlignment: MainAxisAlignment.spaceBetween,
               children: <Widget>[
-                Text('Accelerometer: $accelerometer'),
+                Text('UserAccelerometer: $userAccelerometer'),
               ],
             ),
           ),
@@ -99,7 +99,7 @@ class _MyHomePageState extends State<MyHomePage> {
             child: Row(
               mainAxisAlignment: MainAxisAlignment.spaceBetween,
               children: <Widget>[
-                Text('UserAccelerometer: $userAccelerometer'),
+                Text('Accelerometer: $accelerometer'),
               ],
             ),
           ),
@@ -138,28 +138,28 @@ class _MyHomePageState extends State<MyHomePage> {
   void initState() {
     super.initState();
     _streamSubscriptions.add(
-      accelerometerEvents.listen(
-        (AccelerometerEvent event) {
+      userAccelerometerEvents.listen(
+        (UserAccelerometerEvent event) {
           setState(() {
-            _accelerometerValues = <double>[event.x, event.y, event.z];
+            _userAccelerometerValues = <double>[event.x, event.y, event.z];
           });
         },
       ),
     );
     _streamSubscriptions.add(
-      gyroscopeEvents.listen(
-        (GyroscopeEvent event) {
+      accelerometerEvents.listen(
+        (AccelerometerEvent event) {
           setState(() {
-            _gyroscopeValues = <double>[event.x, event.y, event.z];
+            _accelerometerValues = <double>[event.x, event.y, event.z];
           });
         },
       ),
     );
     _streamSubscriptions.add(
-      userAccelerometerEvents.listen(
-        (UserAccelerometerEvent event) {
+      gyroscopeEvents.listen(
+        (GyroscopeEvent event) {
           setState(() {
-            _userAccelerometerValues = <double>[event.x, event.y, event.z];
+            _gyroscopeValues = <double>[event.x, event.y, event.z];
           });
         },
       ),