Documentation fixes. (#5903)

See #4434.

packages/flutter/lib/src/animation/animations.dart

@@ -605,3 +605,21 @@ abstract class CompoundAnimation<T> extends Animation<T>
     }
   }
 }
+
+/// An animation of [double]s that tracks the mean of two other animations.
+///
+/// The [status] of this animation is the status of the `right` animation if it is
+/// moving, and the `left` animation otherwise.
+///
+/// The [value] of this animation is the [double] that represents the mean value
+/// of the values of the `left` and `right` animations.
+class AnimationMean extends CompoundAnimation<double> {
+  /// Creates an animation that tracks the mean of two other animations.
+  AnimationMean({
+    Animation<double> left,
+    Animation<double> right,
+  }) : super(first: left, next: right);
+
+  @override
+  double get value => (first.value + next.value) / 2.0;
+}

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

@@ -239,6 +239,12 @@ class AppBar extends StatelessWidget {
   final double _expandedHeight;
   final double _collapsedHeight;
 
+  /// Returns the [expandedHeight] of the [AppBar] nearest to the given
+  /// [BuildContext].
+  ///
+  /// Calling this function sets up an inheritance relationship, so that the
+  /// widget corresponding to the given [BuildContext] will rebuild whenever
+  /// that height changes.
   static double getExpandedHeightFor(BuildContext context) {
     _AppBarExpandedHeight marker = context.inheritFromWidgetOfExactType(_AppBarExpandedHeight);
     return marker?.expandedHeight ?? 0.0;
@@ -292,6 +298,8 @@ class AppBar extends StatelessWidget {
   /// The [Scaffold] gives its app bar this height initially. If a
   /// [flexibleSpace] widget is specified this height should be big
   /// enough to accommodate whatever that widget contains.
+  ///
+  /// See also [getExpandedHeightFor].
   double get expandedHeight => _expandedHeight ?? (_toolBarHeight + bottomHeight);
 
   /// By default, the height of the toolbar and the bottom widget (if any).

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

@@ -13,7 +13,7 @@ import 'package:meta/meta.dart';
 // vertical or horizontal.
 const double _kOnAxisDelta = 2.0;
 
-/// A Tween that animates a point along a circular arc.
+/// A [Tween] that animates a [Point] along a circular arc.
 ///
 /// The arc's radius is related to the bounding box that contains the [begin]
 /// and [end] points. If the bounding box is taller than it is wide, then the
@@ -21,14 +21,23 @@ const double _kOnAxisDelta = 2.0;
 /// Otherwise the center of the circle will be aligned with the begin point.
 /// The arc's sweep is always less than or equal to 90 degrees.
 ///
+/// Unlike those of most Tweens, the [begin] and [end] members of a
+/// [MaterialPointArcTween] are immutable.
+///
 /// See also:
 ///
 /// * [MaterialRectArcTween]
 class MaterialPointArcTween extends Tween<Point> {
+  /// Creates a [Tween] for animating [Point]s along a circular arc.
+  ///
+  /// The [begin] and [end] points are required, cannot be null, and are
+  /// immutable.
   MaterialPointArcTween({
     @required Point begin,
     @required Point end
   }) : super(begin: begin, end: end) {
+    assert(begin != null);
+    assert(end != null);
     // An explanation with a diagram can be found at https://goo.gl/vMSdRg
     final Offset delta = end - begin;
     final double deltaX = delta.dx.abs();
@@ -151,20 +160,29 @@ const List<_Diagonal> _allDiagonals = const <_Diagonal>[
   const _Diagonal(_CornerId.bottomLeft, _CornerId.topRight),
 ];
 
-/// A Tween that animates a rectangle from [begin] to [end].
+/// A [Tween] that animates a [Rect] from [begin] to [end].
 ///
 /// The rectangle corners whose diagonal is closest to the overall direction of
 /// the animation follow arcs defined with [MaterialPointArcTween].
 ///
+/// Unlike those of most Tweens, the [begin] and [end] members of a
+/// [MaterialPointArcTween] are immutable.
+///
 /// See also:
 ///
-/// * [RectTween] (linear rectangle interpolation)
-/// * [MaterialPointArcTween]
+/// * [MaterialPointArcTween]. the analogue for [Point] interporation.
+/// * [RectTween], which does a linear rectangle interpolation.
 class MaterialRectArcTween extends RectTween {
+  /// Creates a [Tween] for animating [Rect]s along a circular arc.
+  ///
+  /// The [begin] and [end] points are required, cannot be null, and are
+  /// immutable.
   MaterialRectArcTween({
     @required Rect begin,
     @required Rect end
   }) : super(begin: begin, end: end) {
+    assert(begin != null);
+    assert(end != null);
     final Offset centersVector = end.center - begin.center;
     _diagonal = maxBy(_allDiagonals, (_Diagonal d) => _diagonalSupport(centersVector, d));
     _beginArc = new MaterialPointArcTween(

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

@@ -12,10 +12,17 @@ import 'dart:ui' show lerpDouble;
 ///
 /// All [MergeableMaterialItem] objects need a [LocalKey].
 abstract class MergeableMaterialItem {
-  MergeableMaterialItem(this.key) {
-    assert(key != null);
-  }
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
+  ///
+  /// The argument is the [key], which must not be null.
+  const MergeableMaterialItem(this.key);
 
+  /// The key for this item of the list.
+  ///
+  /// The key is used to match parts of the mergeable material from frame to
+  /// frame so that state is maintained appropriately even as slices are added
+  /// or removed.
   final LocalKey key;
 }
 
@@ -29,7 +36,9 @@ class MaterialSlice extends MergeableMaterialItem {
   MaterialSlice({
     @required LocalKey key,
     this.child
-  }) : super(key);
+  }) : super(key) {
+    assert(key != null);
+  }
 
   /// The contents of this slice.
   final Widget child;
@@ -48,7 +57,9 @@ class MaterialGap extends MergeableMaterialItem {
   MaterialGap({
     @required LocalKey key,
     this.size: 16.0
-  }) : super(key);
+  }) : super(key) {
+    assert(key != null);
+  }
 
   /// The main axis extent of this gap. For example, if the [MergableMaterial]
   /// is vertical, then this is the height of the gap.
@@ -128,7 +139,7 @@ class _AnimationTuple {
 class _MergeableMaterialState extends State<MergeableMaterial> {
   List<MergeableMaterialItem> _children;
   final Map<LocalKey, _AnimationTuple> _animationTuples =
-      new Map<LocalKey, _AnimationTuple>();
+      <LocalKey, _AnimationTuple>{};
 
   @override
   void initState() {

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

@@ -76,16 +76,6 @@ class _CupertinoPageTransition extends AnimatedWidget {
   }
 }
 
-class AnimationMean extends CompoundAnimation<double> {
-  AnimationMean({
-    Animation<double> left,
-    Animation<double> right,
-  }) : super(first: left, next: right);
-
-  @override
-  double get value => (first.value + next.value) / 2.0;
-}
-
 // Custom curve for iOS page transitions.
 class _CupertinoTransitionCurve extends Curve {
   _CupertinoTransitionCurve(this.curve);
@@ -204,21 +194,21 @@ class MaterialPageRoute<T> extends PageRoute<T> {
 
   @override
   void dispose() {
+    _backGestureController?.dispose();
     super.dispose();
-    backGestureController?.dispose();
   }
 
-  _CupertinoBackGestureController backGestureController;
+  _CupertinoBackGestureController _backGestureController;
 
   @override
   NavigationGestureController startPopGesture(NavigatorState navigator) {
-    assert(backGestureController == null);
-    backGestureController = new _CupertinoBackGestureController(
+    assert(_backGestureController == null);
+    _backGestureController = new _CupertinoBackGestureController(
       navigator: navigator,
       controller: controller,
-      onDisposed: () { backGestureController = null; }
+      onDisposed: () { _backGestureController = null; }
     );
-    return backGestureController;
+    return _backGestureController;
   }
 
   @override

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

@@ -80,8 +80,8 @@ enum _DismissTransition {
 /// See also:
 ///
 ///  * <https://www.google.com/design/spec/patterns/swipe-to-refresh.html>
-///  * [RefreshIndicatorState] (can be used to programatically show the refresh indicator)
-///  * [RefreshProgressIndicator]
+///  * [RefreshIndicatorState], can be used to programatically show the refresh indicator.
+///  * [RefreshProgressIndicator].
 class RefreshIndicator extends StatefulWidget {
   /// Creates a refresh indicator.
   ///
@@ -319,10 +319,8 @@ class RefreshIndicatorState extends State<RefreshIndicator> {
   /// been started interactively. If this method is called while the refresh
   /// callback is running, it quietly does nothing.
   ///
-  /// See also:
-  ///
-  /// * [GlobalKey] (creating the RefreshIndicator with a [GlobalKey<RefreshIndicatorState>]
-  ///   will make it possible to refer to the [RefreshIndicatorState] later)
+  /// Creating the RefreshIndicator with a [GlobalKey<RefreshIndicatorState>]
+  /// makes it possible to refer to the [RefreshIndicatorState].
   Future<Null> show() async {
     if (_mode != _RefreshIndicatorMode.refresh) {
       _sizeController.value = 0.0;

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

@@ -128,7 +128,7 @@ class BannerPainter extends CustomPainter {
 ///
 /// See also:
 ///
-///  * [CheckedModeBanner]
+///  * [CheckedModeBanner].
 class Banner extends StatelessWidget {
   /// Creates a banner.
   ///

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

@@ -205,8 +205,8 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
-///  * [CustomPainter]
-///  * [Canvas]
+///  * [CustomPainter].
+///  * [Canvas].
 class CustomPaint extends SingleChildRenderObjectWidget {
   /// Creates a widget that delegates its painting.
   CustomPaint({ Key key, this.painter, this.foregroundPainter, Widget child })
@@ -540,11 +540,11 @@ class Padding extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
-///  * [CustomSingleChildLayout]
-///  * [Center] (which is the same as [Align] but with the [alignment] always
-///    set to [FractionalOffset.center])
-///  * [FractionallySizedBox] (which sizes its child based on a fraction of its own
-///    size and positions the child according to a [FractionalOffset] value)
+///  * [CustomSingleChildLayout].
+///  * [Center], which is the same as [Align] but with the [alignment] always
+///    set to [FractionalOffset.center].
+///  * [FractionallySizedBox], which sizes its child based on a fraction of its own
+///    size and positions the child according to a [FractionalOffset] value.
 class Align extends SingleChildRenderObjectWidget {
   /// Creates an alignment widget.
   ///

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

@@ -349,9 +349,9 @@ class TypeMatcher<T> {
 ///
 /// See also:
 ///
-///  * [StatelessWidget]
-///  * [StatefulWidget]
-///  * [InheritedWidget]
+///  * [StatelessWidget].
+///  * [StatefulWidget].
+///  * [InheritedWidget].
 abstract class Widget {
   /// Initializes [key] for subclasses.
   const Widget({ this.key });
@@ -429,7 +429,7 @@ abstract class Widget {
 ///
 /// See also:
 ///
-///  * [StatefulWidget]
+///  * [StatefulWidget].
 abstract class StatelessWidget extends Widget {
   /// Initializes [key] for subclasses.
   const StatelessWidget({ Key key }) : super(key: key);
@@ -510,8 +510,8 @@ abstract class StatelessWidget extends Widget {
 ///
 /// See also:
 ///
-///  * [State]
-///  * [StatelessWidget]
+///  * [State].
+///  * [StatelessWidget].
 abstract class StatefulWidget extends Widget {
   /// Initializes [key] for subclasses.
   const StatefulWidget({ Key key }) : super(key: key);
@@ -641,8 +641,8 @@ typedef void StateSetter(VoidCallback fn);
 ///
 /// See also:
 ///
-///  * [StatefulWidget]
-///  * [StatelessWidget]
+///  * [StatefulWidget].
+///  * [StatelessWidget].
 @optionalTypeArgs
 abstract class State<T extends StatefulWidget> {
   /// The current configuration.
@@ -758,8 +758,8 @@ abstract class State<T extends StatefulWidget> {
   ///
   /// See also:
   ///
-  /// * [BindingBase.reassembleApplication]
-  /// * [Image], which uses this to reload images
+  /// * [BindingBase.reassembleApplication].
+  /// * [Image], which uses this to reload images.
   @protected
   @mustCallSuper
   void reassemble() { }

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

@@ -45,10 +45,10 @@ import 'framework.dart';
 ///
 /// See also:
 ///
-///  * [Overlay]
-///  * [OverlayState]
-///  * [WidgetsApp]
-///  * [MaterialApp]
+///  * [Overlay].
+///  * [OverlayState].
+///  * [WidgetsApp].
+///  * [MaterialApp].
 class OverlayEntry {
   /// Creates an overlay entry.
   ///
@@ -167,10 +167,10 @@ class _OverlayEntryState extends State<_OverlayEntry> {
 ///
 /// See also:
 ///
-///  * [OverlayEntry]
-///  * [OverlayState]
-///  * [WidgetsApp]
-///  * [MaterialApp]
+///  * [OverlayEntry].
+///  * [OverlayState].
+///  * [WidgetsApp].
+///  * [MaterialApp].
 class Overlay extends StatefulWidget {
   /// Creates an overlay.
   ///

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

@@ -797,7 +797,7 @@ enum ScrollNotificationKind {
 ///
 /// See also:
 ///
-/// * [NotificationListener]
+/// * [NotificationListener].
 class ScrollNotification extends Notification {
   /// Creates a notification about scrolling.
   ScrollNotification({ this.scrollable, this.kind, dynamic details }) : _details = details {
@@ -991,9 +991,9 @@ class ScrollableViewport extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [ScrollableViewport], if you only have one child
-///  * [ScrollableList], if all your children are the same height
-///  * [LazyBlock], if you have children with varying heights
+///  * [ScrollableViewport], if you only have one child.
+///  * [ScrollableList], if all your children are the same height.
+///  * [LazyBlock], if you have children with varying heights.
 class Block extends StatelessWidget {
   /// Creates a scrollable array of children.
   Block({

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

@@ -20,9 +20,9 @@ import 'virtual_viewport.dart';
 ///
 /// See also:
 ///
-///  * [CustomGrid]
-///  * [ScrollableList]
-///  * [ScrollableViewport]
+///  * [CustomGrid].
+///  * [ScrollableList].
+///  * [ScrollableViewport].
 class ScrollableGrid extends StatelessWidget {
   /// Creates a vertically scrollable grid.
   ///
@@ -119,8 +119,8 @@ class ScrollableGrid extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [ListViewport]
-///  * [LazyListViewport]
+///  * [ListViewport].
+///  * [LazyListViewport].
 class GridViewport extends VirtualViewportFromIterable {
   /// Creates a virtual viewport onto a grid of widgets.
   ///

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

@@ -27,9 +27,9 @@ import 'virtual_viewport.dart';
 ///
 /// See also:
 ///
-///  * [ScrollableLazyList]
-///  * [LazyBlock]
-///  * [ScrollableViewport]
+///  * [ScrollableLazyList].
+///  * [LazyBlock].
+///  * [ScrollableViewport].
 class ScrollableList extends StatelessWidget {
   /// Creats a scrollable list of children that have equal size.
   ///
@@ -377,9 +377,9 @@ class _VirtualListViewportElement extends VirtualViewportElement {
 ///
 /// See also:
 ///
-///  * [LazyListViewport]
-///  * [LazyBlockViewport]
-///  * [GridViewport]
+///  * [LazyListViewport].
+///  * [LazyBlockViewport].
+///  * [GridViewport].
 class ListViewport extends _VirtualListViewport with VirtualViewportFromIterable {
   /// Creates a virtual viewport onto a list of equally sized children.
   ///
@@ -420,8 +420,8 @@ class ListViewport extends _VirtualListViewport with VirtualViewportFromIterable
 ///
 /// See also:
 ///
-///  * [ScrollableList]
-///  * [LazyBlock]
+///  * [ScrollableList].
+///  * [LazyBlock].
 class ScrollableLazyList extends StatelessWidget {
   /// Creates an infinite scrollable list of children that have equal size.
   ///
@@ -579,8 +579,8 @@ class ScrollableLazyList extends StatelessWidget {
 ///
 /// See also:
 ///
-///  * [ListViewport]
-///  * [LazyBlockViewport]
+///  * [ListViewport].
+///  * [LazyBlockViewport].
 class LazyListViewport extends _VirtualListViewport with VirtualViewportFromBuilder {
   /// Creates a virtual viewport onto an extremely large or infinite list of equally sized children.
   ///

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

@@ -295,7 +295,7 @@ class RelativeRectTween extends Tween<RelativeRect> {
 ///
 /// See also:
 ///
-/// * [RelativePositionedTransition]
+/// * [RelativePositionedTransition].
 class PositionedTransition extends AnimatedWidget {
   /// Creates a transition for [Positioned].
   ///
@@ -332,7 +332,7 @@ class PositionedTransition extends AnimatedWidget {
 ///
 /// See also:
 ///
-/// * [PositionedTransition]
+/// * [PositionedTransition].
 class RelativePositionedTransition extends AnimatedWidget {
   /// Create an animated version of [Positioned].
   ///