LazyBlock docs and physics

This patch adds dartdoc to LazyBlock. Also, this patch fixes the scrolling
physics of LazyBlock. Previously, we updated a running simulation only when the
change in scroll behavior changed the current scroll offset. Now we update
running simulations every time the behavior changes because the simulation
might depend on quantities other than the current scroll offset.

dev/manual_tests/card_collection.dart

@@ -418,7 +418,7 @@ class CardCollectionState extends State<CardCollection> {
       );
     } else {
       cardCollection = new LazyBlock(
-        delegate: new LazyBlockBuilder(_buildCard),
+        delegate: new LazyBlockBuilder(builder: _buildCard),
         snapOffsetCallback: _snapToCenter ? _toSnapOffset : null
       );
     }

dev/manual_tests/overlay_geometry.dart

@@ -130,7 +130,7 @@ class CardBuilder extends LazyBlockDelegate {
 class OverlayGeometryAppState extends State<OverlayGeometryApp> {
   List<CardModel> cardModels;
   Map<MarkerType, Point> markers = new Map<MarkerType, Point>();
-  double markersScrollOffset;
+  double markersScrollOffset = 0.0;
   ScrollListener scrollListener;
 
   @override

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

@@ -125,9 +125,9 @@ class RenderViewportBase extends RenderBox implements HasMainAxis {
 
   /// The direction in which the child is permitted to be larger than the viewport
   ///
-  /// If the viewport is scrollable in a particular direction (e.g., vertically),
-  /// the child is given layout constraints that are fully unconstrainted in
-  /// that direction (e.g., the child can be as tall as it wants).
+  /// The child is given layout constraints that are fully unconstrainted along
+  /// the main axis (e.g., the child can be as tall as it wants if the main axis
+  /// is vertical).
   @override
   Axis get mainAxis => _mainAxis;
   Axis _mainAxis;

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

@@ -1013,9 +1013,9 @@ class Viewport extends SingleChildRenderObjectWidget {
 
   /// The direction in which the child is permitted to be larger than the viewport
   ///
-  /// If the viewport is scrollable in a particular direction (e.g., vertically),
-  /// the child is given layout constraints that are fully unconstrainted in
-  /// that direction (e.g., the child can be as tall as it wants).
+  /// The child is given layout constraints that are fully unconstrainted along
+  /// the main axis (e.g., the child can be as tall as it wants if the main axis
+  /// is vertical).
   final Axis mainAxis;
 
   final ViewportAnchor anchor;
@@ -1025,6 +1025,7 @@ class Viewport extends SingleChildRenderObjectWidget {
   /// Often used to paint scroll bars.
   final RenderObjectPainter overlayPainter;
 
+  /// Called when the interior or exterior dimensions of the viewport change.
   final ViewportDimensionsChangeCallback onPaintOffsetUpdateNeeded;
 
   @override

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

@@ -162,7 +162,7 @@ abstract class AnimatedWidgetBaseState<T extends ImplicitlyAnimatedWidget> exten
   }
 
   /// Subclasses must implement this function by running through the following
-  /// steps for for each animatable facet in the class:
+  /// steps for each animatable facet in the class:
   ///
   /// 1. Call the visitor callback with three arguments, the first argument
   /// being the current value of the Tween<T> object that represents the

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

@@ -379,9 +379,16 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
     return _controller.animateTo(newScrollOffset, duration: duration, curve: curve).then(_endScroll);
   }
 
+  /// Update any in-progress scrolling physics to account for new scroll behavior.
+  ///
+  /// The scrolling physics depends on the scroll behavior. When changing the
+  /// scrolling behavior, call this function to update any in-progress scrolling
+  /// physics to account for the new scroll behavior. This function preserves
+  /// the current velocity when updating the physics.
+  ///
+  /// If there are no in-progress scrolling physics, this function scrolls to
+  /// the given offset instead.
   void didUpdateScrollBehavior(double newScrollOffset) {
-    if (newScrollOffset == _scrollOffset)
-      return;
     if (_numberOfInProgressScrolls > 0) {
       if (_simulation != null) {
         double dx = _simulation.dx(_controller.lastElapsedDuration.inMicroseconds / Duration.MICROSECONDS_PER_SECOND);

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

@@ -126,8 +126,8 @@ class _GridViewportElement extends VirtualViewportElement {
     super.updateRenderObject(oldWidget);
   }
 
-  double _contentExtent;
-  double _containerExtent;
+  double _lastReportedContentExtent;
+  double _lastReportedContainerExtent;
   GridSpecification _specification;
 
   @override
@@ -146,10 +146,10 @@ class _GridViewportElement extends VirtualViewportElement {
 
     super.layout(constraints);
 
-    if (contentExtent != _contentExtent || containerExtent != _containerExtent) {
-      _contentExtent = contentExtent;
-      _containerExtent = containerExtent;
-      widget.onExtentsChanged(_contentExtent, _containerExtent);
+    if (contentExtent != _lastReportedContentExtent || containerExtent != _lastReportedContainerExtent) {
+      _lastReportedContentExtent = contentExtent;
+      _lastReportedContainerExtent = containerExtent;
+      widget.onExtentsChanged(_lastReportedContentExtent, _lastReportedContainerExtent);
     }
   }
 }

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

@@ -192,8 +192,8 @@ class _VirtualListViewportElement extends VirtualViewportElement {
     super.updateRenderObject(oldWidget);
   }
 
-  double _contentExtent;
-  double _containerExtent;
+  double _lastReportedContentExtent;
+  double _lastReportedContainerExtent;
 
   @override
   void layout(BoxConstraints constraints) {
@@ -253,10 +253,10 @@ class _VirtualListViewportElement extends VirtualViewportElement {
 
     super.layout(constraints);
 
-    if (contentExtent != _contentExtent || containerExtent != _containerExtent) {
-      _contentExtent = contentExtent;
-      _containerExtent = containerExtent;
-      widget.onExtentsChanged(_contentExtent, _containerExtent);
+    if (contentExtent != _lastReportedContentExtent || containerExtent != _lastReportedContainerExtent) {
+      _lastReportedContentExtent = contentExtent;
+      _lastReportedContainerExtent = containerExtent;
+      widget.onExtentsChanged(_lastReportedContentExtent, _lastReportedContainerExtent);
     }
   }
 }

packages/flutter/test/widget/scrollable_list_with_inherited_test.dart

@@ -23,7 +23,7 @@ Widget buildCard(BuildContext context, int index) {
 
 Widget buildFrame() {
   return new LazyBlock(
-    delegate: new LazyBlockBuilder(buildCard)
+    delegate: new LazyBlockBuilder(builder: buildCard)
   );
 }
 

packages/flutter_sprites/lib/src/textured_line.dart

@@ -100,7 +100,7 @@ class TexturedLinePainter {
     List<Vector2> miters = _computeMiterList(vectors, false);
 
     List<Point> vertices = <Point>[];
-    List<int> indicies = <int>[];
+    List<int> indices = <int>[];
     List<Color> verticeColors = <Color>[];
     List<Point> textureCoordinates;
     double textureTop;
@@ -151,8 +151,8 @@ class TexturedLinePainter {
       int lastIndex1 = (i - 1) * 2 + 1;
       int currentIndex0 = i * 2;
       int currentIndex1 = i * 2 + 1;
-      indicies.addAll(<int>[lastIndex0, lastIndex1, currentIndex0]);
-      indicies.addAll(<int>[lastIndex1, currentIndex1, currentIndex0]);
+      indices.addAll(<int>[lastIndex0, lastIndex1, currentIndex0]);
+      indices.addAll(<int>[lastIndex1, currentIndex1, currentIndex0]);
 
       // Add colors
       verticeColors.add(colors[i]);
@@ -170,7 +170,7 @@ class TexturedLinePainter {
       lastMiter = currentMiter;
     }
 
-    canvas.drawVertices(VertexMode.triangles, vertices, textureCoordinates, verticeColors, TransferMode.modulate, indicies, _cachedPaint);
+    canvas.drawVertices(VertexMode.triangles, vertices, textureCoordinates, verticeColors, TransferMode.modulate, indices, _cachedPaint);
   }
 
   double _xPosForStop(double stop) {