Document PointerChange and PointerDeviceKind (flutter#34059)

Author: dkwingsmt

lib/ui/pointer.dart

@@ -38,21 +38,50 @@ enum PointerChange {
   up,
 
   /// A pan/zoom has started on this pointer.
+  ///
+  /// This type of event will always have kind [PointerDeviceKind.trackpad].
   panZoomStart,
 
   /// The pan/zoom on this pointer has updated.
+  ///
+  /// This type of event will always have kind [PointerDeviceKind.trackpad].
   panZoomUpdate,
 
   /// The pan/zoom on this pointer has ended.
+  ///
+  /// This type of event will always have kind [PointerDeviceKind.trackpad].
   panZoomEnd,
 }
 
 /// The kind of pointer device.
 enum PointerDeviceKind {
   /// A touch-based pointer device.
+  ///
+  /// The most common case is a touch screen.
+  ///
+  /// When the user is operating with a trackpad on iOS, clicking will also
+  /// dispatch events with kind [touch] if
+  /// `UIApplicationSupportsIndirectInputEvents` is not present in `Info.plist`
+  /// or returns NO.
+  ///
+  /// See also:
+  ///
+  ///  * [UIApplicationSupportsIndirectInputEvents](https://developer.apple.com/documentation/bundleresources/information_property_list/uiapplicationsupportsindirectinputevents?language=objc).
   touch,
 
   /// A mouse-based pointer device.
+  ///
+  /// The most common case is a mouse on the desktop or Web.
+  ///
+  /// When the user is operating with a trackpad on iOS, moving the pointing
+  /// cursor will also dispatch events with kind [mouse], and clicking will
+  /// dispatch events with kind [mouse] if
+  /// `UIApplicationSupportsIndirectInputEvents` is not present in `Info.plist`
+  /// or returns NO.
+  ///
+  /// See also:
+  ///
+  ///  * [UIApplicationSupportsIndirectInputEvents](https://developer.apple.com/documentation/bundleresources/information_property_list/uiapplicationsupportsindirectinputevents?language=objc).
   mouse,
 
   /// A pointer device with a stylus.
@@ -61,7 +90,31 @@ enum PointerDeviceKind {
   /// A pointer device with a stylus that has been inverted.
   invertedStylus,
 
-  /// A touch-based pointer device with an indirect surface.
+  /// Gestures from a trackpad.
+  ///
+  /// A trackpad here is defined as a touch-based pointer device with an
+  /// indirect surface (the user operates the screen by touching something that
+  /// is not the screen).
+  ///
+  /// When the user makes zoom, pan, scroll or rotate gestures with a physical
+  /// trackpad, supporting platforms dispatch events with kind [trackpad].
+  ///
+  /// Events with kind [trackpad] can only have a [PointerChange] of `add`,
+  /// `remove`, and pan-zoom related values.
+  ///
+  /// Some platforms don't support (or don't fully support) trackpad
+  /// gestures, and might convert trackpad gestures into fake pointer events
+  /// that simulate dragging. These events typically have kind [touch] or
+  /// [mouse] instead of [trackpad]. This includes (but is not limited to) Web,
+  /// and iOS when `UIApplicationSupportsIndirectInputEvents` isn't present in
+  /// `Info.plist` or returns NO.
+  ///
+  /// Moving the pointing cursor or clicking with a trackpad typically triggers
+  /// [touch] or [mouse] events, but never triggers [trackpad] events.
+  ///
+  /// See also:
+  ///
+  ///  * [UIApplicationSupportsIndirectInputEvents](https://developer.apple.com/documentation/bundleresources/information_property_list/uiapplicationsupportsindirectinputevents?language=objc).
   trackpad,
 
   /// An unknown pointer device.