docs: clarify that Position.heading carries course over ground (#1187)

geolocator_platform_interface/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 - Updated `flutter_lints` to version `^5.0.0`.
 
+## 4.2.7
+
+- Clarifies the documentation of `Position.heading` to explain that it carries the course over ground (direction of travel, from `Location.getBearing()` on Android and `CLLocation.course` on iOS), which is distinct from compass heading. The field keeps the `heading` name for backward compatibility. Resolves [#1187](https://github.com/Baseflow/flutter-geolocator/issues/1187).
+
 ## 4.2.6
 
 - Updates documentation `isMocked` to bring it in line with the functionality. `isMocked` for iOS 15 and higher depends on the result from isSimulatedBySoftware.

geolocator_platform_interface/lib/src/models/position.dart

@@ -50,10 +50,22 @@ class Position {
   /// 0.0.
   final double accuracy;
 
-  /// The heading in which the device is traveling in degrees.
+  /// The course over ground (direction of travel) in degrees.
   ///
-  /// The heading is not available on all devices. In these cases the value is
-  /// 0.0.
+  /// This reports the direction in which the device is *moving* across the
+  /// ground, in degrees clockwise relative to true north (0.0 to 360.0). It is
+  /// derived from the platform's GPS-based value: `Location.getBearing()` on
+  /// Android and `CLLocation.course` on iOS.
+  ///
+  /// This is distinct from compass heading: it does *not* report the direction
+  /// the device is physically pointing (the magnetometer/compass reading). A
+  /// stationary device has no meaningful course over ground.
+  ///
+  /// The field is named `heading` for backward compatibility; despite the name
+  /// it carries the course-over-ground value described above.
+  ///
+  /// The course is not available on all devices, and may be unavailable while
+  /// the device is not moving. In these cases the value is 0.0.
   final double heading;
 
   /// The estimated heading accuracy of the position in degrees.

geolocator_platform_interface/pubspec.yaml

@@ -3,7 +3,7 @@ description: A common platform interface for the geolocator plugin.
 repository: https://github.com/baseflow/flutter-geolocator/tree/main/geolocator_platform_interface
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 4.2.6
+version: 4.2.7
 
 
 dependencies: