Docs (#39198)

* Minor improvements to framework documentation.

* maybePop documentation fix

* Mark some flutter_test arguments required.

Without these set, we get a crash.

* Minor correction to ListView docs

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

@@ -118,6 +118,9 @@ class MergeableMaterial extends StatefulWidget {
   /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
   ///
   /// Defaults to 2, the appropriate elevation for cards.
+  ///
+  /// This uses [kElevationToShadow] to simulate shadows, it does not use
+  /// [Material]'s arbitrary elevation feature.
   final int elevation;
 
   /// Whether connected pieces of [MaterialSlice] have dividers between them.

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

@@ -17,9 +17,13 @@ import 'package:flutter/painting.dart';
 /// Each entry has three shadows which must be combined to obtain the defined
 /// effect for that elevation.
 ///
+/// This is useful when simulating a shadow with a [BoxDecoration] or other
+/// class that uses a list of [BoxShadow] objects.
+///
 /// See also:
 ///
-///  * [Material]
+///  * [Material], which takes an arbitrary double for its elevation and generates
+///    a shadow dynamically.
 ///  * <https://material.io/design/environment/elevation.html>
 const Map<int, List<BoxShadow>> kElevationToShadow = _elevationToShadow; // to hide the literal from the docs
 

packages/flutter/lib/src/painting/box_decoration.dart

@@ -169,6 +169,12 @@ class BoxDecoration extends Decoration {
   /// A list of shadows cast by this box behind the box.
   ///
   /// The shadow follows the [shape] of the box.
+  ///
+  /// See also:
+  ///
+  ///  * [kElevationToShadow], for some predefined shadows used in Material
+  ///    Design.
+  ///  * [PhysicalModel], a widget for showing shadows.
   final List<BoxShadow> boxShadow;
 
   /// A gradient to use when filling the box.

packages/flutter/lib/src/painting/box_shadow.dart

@@ -12,8 +12,6 @@ import 'debug.dart';
 
 /// A shadow cast by a box.
 ///
-/// Inherits from [Shadow]
-///
 /// [BoxShadow] can cast non-rectangular shadows if the box is non-rectangular
 /// (e.g., has a border radius or a circular shape).
 ///
@@ -22,6 +20,9 @@ import 'debug.dart';
 /// See also:
 ///
 ///  * [Canvas.drawShadow], which is a more efficient way to draw shadows.
+///  * [PhysicalModel], a widget for showing shadows.
+///  * [kElevationToShadow], for some predefined shadows used in Material
+///    Design.
 ///  * [Shadow], which is the parent class that lacks [spreadRadius].
 @immutable
 class BoxShadow extends ui.Shadow {

packages/flutter/lib/src/painting/shape_decoration.dart

@@ -141,7 +141,13 @@ class ShapeDecoration extends Decoration {
   /// The image is drawn over the [color] or [gradient].
   final DecorationImage image;
 
-  /// A list of shadows cast by this shape behind the shape.
+  /// A list of shadows cast by the [shape].
+  ///
+  /// See also:
+  ///
+  ///  * [kElevationToShadow], for some predefined shadows used in Material
+  ///    Design.
+  ///  * [PhysicalModel], a widget for showing shadows.
   final List<BoxShadow> shadows;
 
   /// The shape to fill the [color], [gradient], and [image] into and to cast as

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

@@ -102,10 +102,11 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild
 ///
 /// See also:
 ///
+///  * [AnimatedOpacity], which fades between nothing and a single child.
+///  * [AnimatedSwitcher], which switches out a child for a new one with a
+///    customizable transition, supporting multiple cross-fades at once.
 ///  * [AnimatedSize], the lower-level widget which [AnimatedCrossFade] uses to
 ///    automatically change size.
-///  * [AnimatedSwitcher], which switches out a child for a new one with a
-///    customizable transition.
 class AnimatedCrossFade extends StatefulWidget {
   /// Creates a cross-fade animation widget.
   ///

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

@@ -10,6 +10,10 @@ import 'framework.dart';
 
 /// Animated widget that automatically transitions its size over a given
 /// duration whenever the given child's size changes.
+///
+/// See also:
+///
+///  * [SizeTransition], which changes its size based on an [Animation].
 class AnimatedSize extends SingleChildRenderObjectWidget {
   /// Creates a widget that animates its size to match that of its child.
   ///

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

@@ -63,8 +63,8 @@ typedef AnimatedSwitcherTransitionBuilder = Widget Function(Widget child, Animat
 /// `currentChild`.
 typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, List<Widget> previousChildren);
 
-/// A widget that by default does a [FadeTransition] between a new widget and
+/// A widget that by default does a cross-fade between a new widget and the
-/// the widget previously set on the [AnimatedSwitcher] as a child.
+/// widget previously set on the [AnimatedSwitcher] as a child.
 ///
 /// If they are swapped fast enough (i.e. before [duration] elapses), more than
 /// one previous child can exist and be transitioning out while the newest one
@@ -140,7 +140,9 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis
 ///
 ///  * [AnimatedCrossFade], which only fades between two children, but also
 ///    interpolates their sizes, and is reversible.
-///  * [FadeTransition] which [AnimatedSwitcher] uses to perform the transition.
+///  * [AnimatedOpacity], which can be used to switch between nothingness and
+///    a given child by fading the child in and out.
+///  * [FadeTransition], which [AnimatedSwitcher] uses to perform the transition.
 class AnimatedSwitcher extends StatefulWidget {
   /// Creates an [AnimatedSwitcher].
   ///

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

@@ -3999,10 +3999,6 @@ class Flex extends MultiChildRenderObjectWidget {
 /// )
 /// ```
 ///
-/// You will see this issue when you run the app:
-///
-/// ![A screenshot of the error using the Row widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_error.png)
-///
 /// The row first asks its first child, the [FlutterLogo], to lay out, at
 /// whatever size the logo would like. The logo is friendly and happily decides
 /// to be 24 pixels to a side. This leaves lots of room for the next child. The
@@ -4015,12 +4011,11 @@ class Flex extends MultiChildRenderObjectWidget {
 /// have no more room available for my other children!", and gets angry and
 /// sprouts a yellow and black strip.
 ///
-/// {@tool sample}
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_error.png)
+///
 /// The fix is to wrap the second child in an [Expanded] widget, which tells the
 /// row that the child should be given the remaining room:
 ///
-/// ![A screenshot of the Row widget after applying the fix](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_fixed.png)
-///
 /// ```dart
 /// Row(
 ///   children: <Widget>[
@@ -4032,7 +4027,6 @@ class Flex extends MultiChildRenderObjectWidget {
 ///   ],
 /// )
 /// ```
-/// {@end-tool}
 ///
 /// Now, the row first asks the logo to lay out, and then asks the _icon_ to lay
 /// out. The [Icon], like the logo, is happy to take on a reasonable size (also
@@ -4042,6 +4036,8 @@ class Flex extends MultiChildRenderObjectWidget {
 /// text, now happy to comply to a reasonable request, wraps the text within
 /// that width, and you end up with a paragraph split over several lines.
 ///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_fixed.png)
+///
 /// ## Layout algorithm
 ///
 /// _This section describes how a [Row] is rendered by the framework._

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

@@ -5008,6 +5008,15 @@ abstract class RenderObjectElement extends Element {
   /// this element has a single child, the slot should always be null. If this
   /// element has a list of children, the previous sibling is a convenient value
   /// for the slot.
+  ///
+  /// This method is only ever called if [updateChild] can end up being called
+  /// with an existing [Element] child and a `slot` that differs from the slot
+  /// that element was previously given. [MultiChildRenderObjectElement] does this,
+  /// for example. [SingleChildRenderObjectElement] does not (since the `slot` is
+  /// always null). An [Element] that has a specific set of slots with each child
+  /// always having the same slot (and where children in different slots are never
+  /// compared against each other for the purposes of updating one slot with the
+  /// element from another slot) would never call this.
   @protected
   void moveChildRenderObject(covariant RenderObject child, covariant dynamic slot);
 

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

@@ -1259,6 +1259,8 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState<Animat
 ///
 /// See also:
 ///
+///  * [AnimatedCrossFade], for fading between two children.
+///  * [AnimatedSwitcher], for fading between many children in sequence.
 ///  * [FadeTransition], an explicitly animated version of this widget, where
 ///    an [Animation] is provided by the caller instead of being built in.
 class AnimatedOpacity extends ImplicitlyAnimatedWidget {

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

@@ -63,7 +63,7 @@ enum RoutePopDisposition {
 
   /// Delegate this to the next level of navigation.
   ///
-  /// If [Route.willPop] return [bubble] then the back button will be handled
+  /// If [Route.willPop] returns [bubble] then the back button will be handled
   /// by the [SystemNavigator], which will usually close the application.
   bubble,
 }
@@ -143,7 +143,7 @@ abstract class Route<T> {
   @mustCallSuper
   void didReplace(Route<dynamic> oldRoute) { }
 
-  /// Returns false if this route wants to veto a [Navigator.pop]. This method is
+  /// Returns whether this route wants to veto a [Navigator.pop]. This method is
   /// called by [Navigator.maybePop].
   ///
   /// By default, routes veto a pop if they're the first route in the history
@@ -1304,12 +1304,18 @@ class Navigator extends StatefulWidget {
     return navigator != null && navigator.canPop();
   }
 
-  /// Returns the value of the current route's [Route.willPop] method for the
+  /// Tries to pop the current route of the navigator that most tightly encloses
-  /// navigator that most tightly encloses the given context.
+  /// the given context, while honoring the route's [Route.willPop]
+  /// state.
   ///
   /// {@template flutter.widgets.navigator.maybePop}
-  /// This method is typically called before a user-initiated [pop]. For example
+  /// Returns false if the route deferred to the next enclosing navigator
-  /// on Android it's called by the binding for the system's back button.
+  /// (possibly the system); otherwise, returns true (whether the route was
+  /// popped or not).
+  ///
+  /// This method is typically called to handle a user-initiated [pop]. For
+  /// example on Android it's called by the binding for the system's back
+  /// button.
   ///
   /// The `T` type argument is the type of the return value of the current
   /// route.
@@ -2017,8 +2023,8 @@ class NavigatorState extends State<Navigator> with TickerProviderStateMixin {
     return _history.length > 1 || _history[0].willHandlePopInternally;
   }
 
-  /// Returns the value of the current route's [Route.willPop] method for the
+  /// Tries to pop the current route, while honoring the route's [Route.willPop]
-  /// navigator.
+  /// state.
   ///
   /// {@macro flutter.widgets.navigator.maybePop}
   ///

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

@@ -768,8 +768,8 @@ abstract class BoxScrollView extends ScrollView {
 /// [new ListView] constructor's `children` argument corresponds to the
 /// [childrenDelegate] being a [SliverChildListDelegate] with that same
 /// argument. The [new ListView.builder] constructor's `itemBuilder` and
-/// `childCount` arguments correspond to the [childrenDelegate] being a
+/// `itemCount` arguments correspond to the [childrenDelegate] being a
-/// [SliverChildBuilderDelegate] with the matching arguments.
+/// [SliverChildBuilderDelegate] with the equivalent arguments.
 ///
 /// The [padding] property corresponds to having a [SliverPadding] in the
 /// [CustomScrollView.slivers] property instead of the list itself, and having

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

@@ -127,7 +127,11 @@ abstract class SliverChildDelegate {
   /// return a precise non-null value.
   ///
   /// Subclasses typically override this function and wrap their children in
-  /// [AutomaticKeepAlive] and [RepaintBoundary] widgets.
+  /// [AutomaticKeepAlive], [IndexedSemantics], and [RepaintBoundary] widgets.
+  ///
+  /// The values returned by this method are cached. To indicate that the
+  /// widgets have changed, a new delegate must be provided, and the new
+  /// delegate's [shouldRebuild] method must return true.
   Widget build(BuildContext context, int index);
 
   /// Returns an estimate of the number of children this delegate will build.
@@ -711,6 +715,10 @@ abstract class SliverWithKeepAliveWidget extends RenderObjectWidget {
 /// A base class for sliver that have multiple box children.
 ///
 /// Helps subclasses build their children lazily using a [SliverChildDelegate].
+///
+/// The widgets returned by the [delegate] are cached and the delegate is only
+/// consulted again if it changes and the new delegate's [shouldRebuild] method
+/// returns true.
 abstract class SliverMultiBoxAdaptorWidget extends SliverWithKeepAliveWidget {
   /// Initializes fields for subclasses.
   const SliverMultiBoxAdaptorWidget({
@@ -722,7 +730,7 @@ abstract class SliverMultiBoxAdaptorWidget extends SliverWithKeepAliveWidget {
   /// {@template flutter.widgets.sliverChildDelegate}
   /// The delegate that provides the children for this widget.
   ///
-  /// The children are constructed lazily using this widget to avoid creating
+  /// The children are constructed lazily using this delegate to avoid creating
   /// more children than are visible through the [Viewport].
   ///
   /// See also:

packages/flutter_test/lib/src/finders.dart

@@ -244,7 +244,12 @@ class CommonFinders {
   ///
   /// If the [skipOffstage] argument is true (the default), then nodes that are
   /// [Offstage] or that are from inactive [Route]s are skipped.
-  Finder descendant({ Finder of, Finder matching, bool matchRoot = false, bool skipOffstage = true }) {
+  Finder descendant({
+    @required Finder of,
+    @required Finder matching,
+    bool matchRoot = false,
+    bool skipOffstage = true,
+  }) {
     return _DescendantFinder(of, matching, matchRoot: matchRoot, skipOffstage: skipOffstage);
   }
 
@@ -269,7 +274,11 @@ class CommonFinders {
   ///
   /// If the [matchRoot] argument is true then the widget(s) specified by [of]
   /// will be matched along with the ancestors.
-  Finder ancestor({ Finder of, Finder matching, bool matchRoot = false }) {
+  Finder ancestor({
+    @required Finder of,
+    @required Finder matching,
+    bool matchRoot = false,
+  }) {
     return _AncestorFinder(of, matching, matchRoot: matchRoot);
   }