Improve dartdoc comments for gestures.dart (#4000)

Also, make some previously private classes public for better
documentation.

packages/flutter/lib/src/gestures/drag.dart

@@ -54,7 +54,11 @@ typedef void GesturePanEndCallback(Velocity velocity);
 /// [GesturePanDownCallback] did not complete.
 typedef void GesturePanCancelCallback();
 
-typedef void _GesturePolymorphicUpdateCallback<T>(T delta);
+/// Signature for when a pointer that is in contact with the screen and moving
+/// has moved again. For one-dimensional drags (e.g., horizontal or vertical),
+/// T is `double`, as in [GestureDragUpdateCallback]. For two-dimensional drags
+/// (e.g., pans), T is `Offset`, as in GesturePanUpdateCallback.
+typedef void GesturePolymorphicUpdateCallback<T>(T delta);
 
 bool _isFlingGesture(Velocity velocity) {
   assert(velocity != null);
@@ -62,7 +66,25 @@ bool _isFlingGesture(Velocity velocity) {
   return speedSquared > kMinFlingVelocity * kMinFlingVelocity;
 }
 
-abstract class _DragGestureRecognizer<T extends dynamic> extends OneSequenceGestureRecognizer {
+/// Recognizes movement.
+///
+/// In contrast to [MultiDragGestureRecognizer], [DragGestureRecognizer]
+/// recognizes a single gesture sequence for all the pointers it watches, which
+/// means that the recognizer has at most one drag sequence active at any given
+/// time regardless of how many pointers are in contact with the screen.
+///
+/// [DragGestureRecognizer] is not intended to be used directly. Instead,
+/// consider using one of its subclasses to recognize specific types for drag
+/// gestures.
+///
+/// See also:
+///
+///  * [HorizontalDragGestureRecognizer]
+///  * [VerticalDragGestureRecognizer]
+///  * [PanGestureRecognizer]
+// Having T extend dynamic makes it possible to use the += operator on
+// _pendingDragDelta without causing an analysis error.
+abstract class DragGestureRecognizer<T extends dynamic> extends OneSequenceGestureRecognizer {
   /// A pointer has contacted the screen and might begin to move.
   GestureDragDownCallback onDown;
 
@@ -70,15 +92,14 @@ abstract class _DragGestureRecognizer<T extends dynamic> extends OneSequenceGest
   GestureDragStartCallback onStart;
 
   /// A pointer that is in contact with the screen and moving has moved again.
-  _GesturePolymorphicUpdateCallback<T> onUpdate;
+  GesturePolymorphicUpdateCallback<T> onUpdate;
 
   /// A pointer that was previously in contact with the screen and moving is no
   /// longer in contact with the screen and was moving at a specific velocity
   /// when it stopped contacting the screen.
   GestureDragEndCallback onEnd;
 
-  /// Signature for when the pointer that previously triggered [onDown] did not
-  /// complete.
+  /// The pointer that previously triggered [onDown] did not complete.
   GestureDragCancelCallback onCancel;
 
   _DragState _state = _DragState.ready;
@@ -184,7 +205,7 @@ abstract class _DragGestureRecognizer<T extends dynamic> extends OneSequenceGest
 /// See also:
 ///
 ///  * [VerticalMultiDragGestureRecognizer]
-class VerticalDragGestureRecognizer extends _DragGestureRecognizer<double> {
+class VerticalDragGestureRecognizer extends DragGestureRecognizer<double> {
   @override
   double get _initialPendingDragDelta => 0.0;
 
@@ -205,7 +226,7 @@ class VerticalDragGestureRecognizer extends _DragGestureRecognizer<double> {
 /// See also:
 ///
 ///  * [HorizontalMultiDragGestureRecognizer]
-class HorizontalDragGestureRecognizer extends _DragGestureRecognizer<double> {
+class HorizontalDragGestureRecognizer extends DragGestureRecognizer<double> {
   @override
   double get _initialPendingDragDelta => 0.0;
 
@@ -225,7 +246,7 @@ class HorizontalDragGestureRecognizer extends _DragGestureRecognizer<double> {
 ///
 ///  * [ImmediateMultiDragGestureRecognizer]
 ///  * [DelayedMultiDragGestureRecognizer]
-class PanGestureRecognizer extends _DragGestureRecognizer<Offset> {
+class PanGestureRecognizer extends DragGestureRecognizer<Offset> {
   @override
   Offset get _initialPendingDragDelta => Offset.zero;
 

packages/flutter/lib/src/gestures/multidrag.dart

@@ -151,11 +151,9 @@ abstract class MultiDragPointerState {
 
 /// Recognizes movement on a per-pointer basis.
 ///
-/// In contrast to [HorizontalDragGestureRecognizer],
-/// [VerticalDragGestureRecognizer], and [PanGestureRecognizer],
-/// [MultiDragGestureRecognizer] watches each pointer separately, which means
-/// multiple drags can be recognized concurrently if multiple pointers are in
-/// contact with the screen.
+/// In contrast to [DragGestureRecognizer], [MultiDragGestureRecognizer] watches
+/// each pointer separately, which means multiple drags can be recognized
+/// concurrently if multiple pointers are in contact with the screen.
 ///
 /// [MultiDragGestureRecognizer] is not intended to be used directly. Instead,
 /// consider using one of its subclasses to recognize specific types for drag

packages/flutter/lib/src/gestures/recognizer.dart

@@ -68,7 +68,7 @@ abstract class OneSequenceGestureRecognizer extends GestureRecognizer {
   @override
   void rejectGesture(int pointer) { }
 
-  /// Called when the number of pointers this recognizers is tracking changes from one to zero.
+  /// Called when the number of pointers this recognizer is tracking changes from one to zero.
   ///
   /// The given pointer ID is the ID of the last pointer this recognizer was
   /// tracking.
@@ -141,7 +141,7 @@ enum GestureRecognizerState {
   /// The recognizer is ready to start recognizing a gesture.
   ready,
 
-  /// The sequence of pointer events seen thus far are consistent with the
+  /// The sequence of pointer events seen thus far is consistent with the
   /// gesture the recognizer is attempting to recognize but the gesture has not
   /// been accepted definitively.
   possible,

packages/flutter/lib/src/gestures/scale.dart

@@ -12,22 +12,22 @@ enum ScaleState {
   /// The recognizer is ready to start recognizing a gesture.
   ready,
 
-  /// The sequence of pointer events seen thus far are consistent with a scale
+  /// The sequence of pointer events seen thus far is consistent with a scale
   /// gesture but the gesture has not been accepted definitively.
   possible,
 
-  /// The sequence of pointer events seen thus far have been accepted
+  /// The sequence of pointer events seen thus far has been accepted
   /// definitively as a scale gesture.
   accepted,
 
-  /// The sequence of pointer events seen thus far have been accepted
+  /// The sequence of pointer events seen thus far has been accepted
   /// definitively as a scale gesture and the pointers established a focal point
   /// and initial scale.
   started,
 }
 
-/// Signature for when the pointers in contact with the screen have begun
-/// established a focal point and initial scale of 1.0.
+/// Signature for when the pointers in contact with the screen have established
+/// a focal point and initial scale of 1.0.
 typedef void GestureScaleStartCallback(Point focalPoint);
 
 /// Signature for when the pointers in contact with the screen have indicated a
@@ -45,8 +45,8 @@ typedef void GestureScaleEndCallback();
 /// change, the recognizer calls [onUpdate]. When the pointers are no longer in
 /// contact with the screen, the recognizer calls [onEnd].
 class ScaleGestureRecognizer extends OneSequenceGestureRecognizer {
-  /// The pointers in contact with the screen have begun established a focal
-  /// point and initial scale of 1.0.
+  /// The pointers in contact with the screen have established a focal point and
+  /// initial scale of 1.0.
   GestureScaleStartCallback onStart;
 
   /// The pointers in contact with the screen have indicated a new focal point

packages/flutter/lib/src/widgets/gesture_detector.dart

@@ -178,8 +178,8 @@ class GestureDetector extends StatelessWidget {
   /// The pointer that previously triggered [onPanDown] did not complete.
   final GesturePanCancelCallback onPanCancel;
 
-  /// The pointers in contact with the screen have begun established a focal
-  /// point and initial scale of 1.0.
+  /// The pointers in contact with the screen have established a focal point and
+  /// initial scale of 1.0.
   final GestureScaleStartCallback onScaleStart;
 
   /// The pointers in contact with the screen have indicated a new focal point