Document typedefs better. (#6671)

packages/flutter/lib/src/material/material.dart

@@ -13,7 +13,9 @@ import 'constants.dart';
 import 'shadows.dart';
 import 'theme.dart';
 
-/// Signature for callback used by ink effects to obtain the rectangle for the effect.
+/// Signature for the callback used by ink effects to obtain the rectangle for the effect.
+///
+/// Used by [MaterialInkController.splashAt], for example.
 typedef Rect RectCallback();
 
 /// The various kinds of material in material design. Used to

packages/flutter/lib/src/material/popup_menu.dart

@@ -447,11 +447,17 @@ Future<dynamic/*=T*/> showMenu/*<T>*/({
   ));
 }
 
-/// A callback that is passed the value of the PopupMenuItem that caused
-/// its menu to be dismissed.
+/// Signature for the callback invoked when a menu item is selected. The
+/// argument is the value of the [PopupMenuItem] that caused its menu to be
+/// dismissed.
+///
+/// Used by [PopupMenuButton.onSelected].
 typedef void PopupMenuItemSelected<T>(T value);
 
-/// Signature used by [PopupMenuButton] to lazily construct the items shown when the button is pressed.
+/// Signature used by [PopupMenuButton] to lazily construct the items shown when
+/// the button is pressed.
+///
+/// Used by [PopupMenuButton.itemBuilder].
 typedef List<PopupMenuEntry<T>> PopupMenuItemBuilder<T>(BuildContext context);
 
 /// Displays a menu when pressed and calls [onSelected] when the menu is dismissed

packages/flutter/lib/src/material/refresh_indicator.dart

@@ -28,10 +28,12 @@ const Duration _kIndicatorSnapDuration = const Duration(milliseconds: 150);
 // has completed.
 const Duration _kIndicatorScaleDuration = const Duration(milliseconds: 200);
 
-/// The signature for a function that's called when the user has dragged the
-/// refresh indicator far enough to demonstrate that they want the app to
-/// refresh. The returned Future must complete when the refresh operation
-/// is finished.
+/// The signature for a function that's called when the user has dragged a
+/// [RefreshIndicator] far enough to demonstrate that they want the app to
+/// refresh. The returned [Future] must complete when the refresh operation is
+/// finished.
+///
+/// Used by [RefreshIndicator.refresh].
 typedef Future<Null> RefreshCallback();
 
 /// Where the refresh indicator appears: top for over-scrolls at the
@@ -117,7 +119,7 @@ class RefreshIndicator extends StatefulWidget {
 
   /// A function that's called when the user has dragged the refresh indicator
   /// far enough to demonstrate that they want the app to refresh. The returned
-  /// Future must complete when the refresh operation is finished.
+  /// [Future] must complete when the refresh operation is finished.
   final RefreshCallback refresh;
 
   /// Where the refresh indicator should appear, [RefreshIndicatorLocation.top]

packages/flutter/lib/src/material/tabs.dart

@@ -290,11 +290,9 @@ class _TabBarWrapper extends MultiChildRenderObjectWidget {
   }
 }
 
-/// Signature for building icons for tabs.
+/// Signature for building icons for [TabLabel]s.
 ///
-/// See also:
-///
-///  * [TabLabel]
+/// Used by [TabLabel.iconBuilder].
 typedef Widget TabLabelIconBuilder(BuildContext context, Color color);
 
 /// Each TabBar tab can display either a title [text], an icon, or both. An icon

packages/flutter/lib/src/rendering/editable_line.dart

@@ -16,7 +16,10 @@ const double _kCaretWidth = 1.0; // pixels
 
 final String _kZeroWidthSpace = new String.fromCharCode(0x200B);
 
-/// Called when the user changes the selection (including cursor location).
+/// Signature for the callback that reports when the user changes the selection
+/// (including the cursor location).
+///
+/// Used by [RenderEditable.onSelectionChanged].
 typedef void SelectionChangedHandler(TextSelection selection, RenderEditable renderObject, bool longPress);
 
 /// Represents a global screen coordinate of the point in a selection, and the
@@ -36,6 +39,12 @@ class TextSelectionPoint {
   final TextDirection direction;
 }
 
+/// Signature for the callback used by [RenderEditable] to determine the paint offset when
+/// the dimensions of the render box change.
+///
+/// The return value should be the new paint offset to use.
+///
+/// Used by [RenderEditable.onPaintOffsetUpdateNeeded].
 typedef Offset RenderEditablePaintOffsetNeededCallback(ViewportDimensions dimensions, Rect caretRect);
 
 /// A single line of editable text.

packages/flutter/lib/src/rendering/object.dart

@@ -41,6 +41,8 @@ class ParentData {
 ///
 /// The `offset` argument is the offset from the origin of the coordinate system
 /// of the [PaintingContext.canvas] to the coordinate system of the callee.
+///
+/// Used by many of the methods of [PaintingContext].
 typedef void PaintingContextCallback(PaintingContext context, Offset offset);
 
 /// A place to paint.
@@ -463,9 +465,13 @@ abstract class Constraints {
 }
 
 /// Signature for a function that is called for each [RenderObject].
+///
+/// Used by [RenderObject.visitChildren] and [RenderObject.visitChildrenForSemantics].
 typedef void RenderObjectVisitor(RenderObject child);
 
 /// Signature for a function that is called during layout.
+///
+/// Used by [RenderObject.invokeLayoutCallback].
 typedef void LayoutCallback(Constraints constraints);
 
 class _SemanticsGeometry {

packages/flutter/lib/src/rendering/semantics.dart

@@ -44,6 +44,8 @@ typedef void SemanticsAnnotator(SemanticsNode semantics);
 /// Signature for a function that is called for each [SemanticsNode].
 ///
 /// Return false to stop visiting nodes.
+///
+/// Used by [SemanticsNode.visitChildren].
 typedef bool SemanticsNodeVisitor(SemanticsNode node);
 
 /// Summary information about a [SemanticsNode] object.

packages/flutter/lib/src/rendering/viewport.dart

@@ -193,6 +193,8 @@ class RenderViewportBase extends RenderBox {
 }
 
 /// Signature for notifications about [RenderViewport] dimensions changing.
+///
+/// Used by [RenderViewport.onPaintOffsetUpdateNeeded].
 typedef Offset ViewportDimensionsChangeCallback(ViewportDimensions dimensions);
 
 /// A render object that's bigger on the inside.

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

@@ -22,6 +22,8 @@ import 'text.dart';
 import 'title.dart';
 
 /// Signature for a function that is called when the operating system changes the current locale.
+///
+/// Used by [WidgetsApp.onLocaleChanged].
 typedef Future<LocaleQueryData> LocaleChangedCallback(Locale locale);
 
 /// A convenience class that wraps a number of widgets that are commonly

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

@@ -2958,7 +2958,7 @@ class KeyedSubtree extends StatelessWidget {
   }
 
   /// Wrap each item in a KeyedSubtree whose key is based on the item's existing key or
-  /// its list index + baseIndex.
+  /// the sum of its list index and `baseIndex`.
   static List<Widget> ensureUniqueKeysForList(Iterable<Widget> items, { int baseIndex: 0 }) {
     if (items == null || items.isEmpty)
       return items;
@@ -2982,7 +2982,7 @@ class KeyedSubtree extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [StatefulBuilder] (which also has state)
+///  * [StatefulBuilder], a platonic widget which also has state.
 class Builder extends StatelessWidget {
   /// Creates a widget that delegates its build to a callback.
   ///
@@ -3016,7 +3016,7 @@ typedef Widget StatefulWidgetBuilder(BuildContext context, StateSetter setState)
 ///
 /// See also:
 ///
-///  * [Builder] (which lacks state)
+///  * [Builder], the platonic stateless widget.
 class StatefulBuilder extends StatefulWidget {
   /// Creates a widget that both has state and delegates its build to a callback.
   ///

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

@@ -7,12 +7,6 @@ import 'package:meta/meta.dart';
 import 'framework.dart';
 import 'scrollable.dart';
 
-/// Signature for building the contents of a scrollable widget.
-///
-/// Typically returns a tree of widgets that includes the viewport that will be
-/// scrolled to the given `scrollOffset`.
-typedef Widget ViewportBuilder(BuildContext context, ScrollableState state, double scrollOffset);
-
 /// A widget that controls whether viewport descendants will overscroll their contents.
 /// Overscrolling is clamped at the beginning or end or both according to the
 /// [edge] parameter.

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

@@ -17,7 +17,10 @@ const double _kMinFlingVelocityDelta = 400.0;
 const double _kFlingVelocityScale = 1.0 / 300.0;
 const double _kDismissThreshold = 0.4;
 
-/// Signature used by [Dismissable] to indicate that it has been dismissed in the given `direction`.
+/// Signature used by [Dismissable] to indicate that it has been dismissed in
+/// the given `direction`.
+///
+/// Used by [Dismissable.onDismissed].
 typedef void DismissDirectionCallback(DismissDirection direction);
 
 /// The direction in which a [Dismissable] can be dismissed.

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

@@ -13,9 +13,13 @@ import 'framework.dart';
 import 'overlay.dart';
 
 /// Signature for determining whether the given data will be accepted by a [DragTarget].
+///
+/// Used by [DragTarget.onWillAccept].
 typedef bool DragTargetWillAccept<T>(T data);
 
 /// Signature for causing a [DragTarget] to accept the given data.
+///
+/// Used by [DragTarget.onAccept].
 typedef void DragTargetAccept<T>(T data);
 
 /// Signature for building children of a [DragTarget].
@@ -24,9 +28,13 @@ typedef void DragTargetAccept<T>(T data);
 /// over this [DragTarget] and that has passed [DragTarget.onWillAccept]. The
 /// `rejectedData` argument contains the list of drag data that is hovering over
 /// this [DragTarget] and that will not be accepted by the [DragTarget].
+///
+/// Used by [DragTarget.builder].
 typedef Widget DragTargetBuilder<T>(BuildContext context, List<T> candidateData, List<dynamic> rejectedData);
 
 /// Signature for when a [Draggable] is dropped without being accepted by a [DragTarget].
+///
+/// Used by [Draggable.onDraggableCanceled].
 typedef void DraggableCanceledCallback(Velocity velocity, Offset offset);
 
 /// Where the [Draggable] should be anchored during a drag.

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

@@ -116,12 +116,18 @@ class _FormScope extends InheritedWidget {
 }
 
 /// Signature for validating a form field.
+///
+/// Used by [FormField.validator].
 typedef String FormFieldValidator<T>(T value);
 
 /// Signature for being notified when a form field changes value.
+///
+/// Used by [FormField.onSaved].
 typedef void FormFieldSetter<T>(T newValue);
 
 /// Signature for building the widget representing the form field.
+///
+/// Used by [FormField.builder].
 typedef Widget FormFieldBuilder<T>(FormFieldState<T> field);
 
 /// A single form field. This widget maintains the current state of the form

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

@@ -110,6 +110,8 @@ class ObjectKey extends LocalKey {
 }
 
 /// Signature for a callback when a global key is removed from the tree.
+///
+/// Used by [GlobalKey.registerRemoveListener].
 typedef void GlobalKeyRemoveListener(GlobalKey key);
 
 /// A key that is unique across the entire app.
@@ -222,7 +224,7 @@ abstract class GlobalKey<T extends State<StatefulWidget>> extends Key {
   /// Stop calling `listener` whenever a widget with the given global key is
   /// removed from the tree.
   ///
-  /// Listeners can be added with [addListener].
+  /// Listeners can be added with [registerRemoveListener].
   static void unregisterRemoveListener(GlobalKey key, GlobalKeyRemoveListener listener) {
     assert(key != null);
     assert(_removeListeners.containsKey(key));
@@ -2780,10 +2782,16 @@ abstract class BuildableElement extends Element {
   }
 }
 
-/// Signature for a function that creates a widget.
+/// Signature for a function that creates a widget, e.g. [StatelessWidget.build]
+/// or [State.build].
+///
+/// Used by [Builder.builder], [OverlayEntry.builder], etc.
 typedef Widget WidgetBuilder(BuildContext context);
 
-/// Signature for a function that creates a widget for a given index, e.g., in a list.
+/// Signature for a function that creates a widget for a given index, e.g., in a
+/// list.
+///
+/// Used by [LazyBlockBuilder.builder].
 typedef Widget IndexedWidgetBuilder(BuildContext context, int index);
 
 // See ComponentElement._builder.

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

@@ -37,6 +37,8 @@ export 'package:flutter/gestures.dart' show
 ///
 /// The `recognizer` argument is the gesture recognizer that currently occupies
 /// the slot for which a gesture recognizer is being created.
+///
+/// Used by [RawGestureDetector.gestures].
 typedef GestureRecognizer GestureRecognizerFactory(GestureRecognizer recognizer);
 
 /// A widget that detects gestures.

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

@@ -108,10 +108,13 @@ abstract class ImplicitlyAnimatedWidget extends StatefulWidget {
   }
 }
 
-/// Used by [AnimatedWidgetBaseState].
+/// Signature for a [Tween] factory.
+///
+/// This is the type of one of the arguments of [TweenVisitor], the signature
+/// used by [AnimatedWidgetBaseState.forEachTween].
 typedef Tween<T> TweenConstructor<T>(T targetValue);
 
-/// Used by [AnimatedWidgetBaseState].
+/// Signature for callbacks passed to [AnimatedWidgetBaseState.forEachTween].
 typedef Tween<T> TweenVisitor<T>(Tween<T> tween, T targetValue, TweenConstructor<T> constructor);
 
 /// A base class for widgets with implicit animations.

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

@@ -162,6 +162,8 @@ class RouteSettings {
 }
 
 /// Creates a route for the given route settings.
+///
+/// Used by [Navigator.onGenerateRoute] and [Navigator.onUnknownRoute].
 typedef Route<dynamic> RouteFactory(RouteSettings settings);
 
 /// An interface for observing the behavior of a [Navigator].

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

@@ -4,7 +4,11 @@
 
 import 'framework.dart';
 
+/// Signature for [Notification] listeners.
+///
 /// Return true to cancel the notification bubbling.
+///
+/// Used by [NotificationListener.onNotification].
 typedef bool NotificationListenerCallback<T extends Notification>(T notification);
 
 /// A notification that can bubble up the widget tree.

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

@@ -10,8 +10,19 @@ import 'layout_builder.dart';
 import 'media_query.dart';
 
 /// Signature for a function that builds a widget given an [Orientation].
+///
+/// Used by [OrientationBuilder.builder].
 typedef Widget OrientationWidgetBuilder(BuildContext context, Orientation orientation);
 
+/// Builds a widget tree that can depend on the parent widget's orientation.
+///
+/// See also:
+///
+/// * [LayoutBuilder], which exposes the complete constraints, not just the
+///   orientation.
+/// * [CustomSingleChildLayout], which positions its child during layout.
+/// * [CustomMultiChildLayout], with which you can define the precise layout
+///   of a list of children during the layout phase.
 class OrientationBuilder extends StatelessWidget {
   /// Creates an orientation builder.
   ///

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

@@ -47,6 +47,8 @@ final Tolerance kPixelScrollTolerance = new Tolerance(
 );
 
 /// Signature for building a widget based on [ScrollableState].
+///
+/// Used by [Scrollable.builder].
 typedef Widget ScrollBuilder(BuildContext context, ScrollableState state);
 
 /// Signature for callbacks that receive a scroll offset.

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

@@ -43,6 +43,12 @@ enum TextSelectionHandleType {
 /// [start] handle always moves the [start]/[baseOffset] of the selection.
 enum _TextSelectionHandlePosition { start, end }
 
+/// Signature for reporting changes to the selection component of an
+/// [InputValue] for the purposes of a [TextSelectionOverlay]. The [caretRect]
+/// argument gives the location of the caret in the coordinate space of the
+/// [RenderBox] given by the [TextSelectionOverlay.renderObject].
+///
+/// Used by [TextSelectionOverlay.onSelectionOverlayChanged].
 typedef void TextSelectionOverlayChanged(InputValue value, Rect caretRect);
 
 /// An interface for manipulating the selection, to be used by the implementor

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

@@ -373,6 +373,10 @@ class RelativePositionedTransition extends AnimatedWidget {
 }
 
 /// A builder that builds a widget given a child.
+///
+/// The child should typically be part of the returned widget tree.
+///
+/// Used by [AnimatedBuilder.builder].
 typedef Widget TransitionBuilder(BuildContext context, Widget child);
 
 /// A general-purpose widget for building animations.

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

@@ -18,6 +18,9 @@ import 'framework.dart';
 ///  * The [containerExtent] is the exterior dimension of the viewport (i.e.,
 ///    the amount of the thing inside the viewport that is visible from outside
 ///    the viewport).
+///
+/// Used by [ScrollableGrid.onExtentsChanged],
+/// [ScrollableList.onExtentsChanged], etc.
 typedef void ExtentsChangedCallback(double contentExtent, double containerExtent);
 
 /// An abstract widget whose children are not all materialized.
@@ -279,6 +282,8 @@ class _IterableWidgetProvider extends _WidgetProvider {
 }
 
 /// Signature of a callback that returns the sublist of widgets in the given range.
+///
+/// Used by [PageableList.itemBuilder], [ScrollableLazyList.itemBuilder], etc.
 typedef List<Widget> ItemListBuilder(BuildContext context, int start, int count);
 
 /// A VirtualViewport that represents its children using [ItemListBuilder].