Random cleanup across the tree (#14221)

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

@@ -252,6 +252,14 @@ class NestedScrollView extends StatefulWidget {
   /// the [PrimaryScrollController] provided by the [NestedScrollView].
   final Widget body;
 
+  /// Returns the [SliverOverlapAbsorberHandle] of the nearest ancestor
+  /// [NestedScrollView].
+  ///
+  /// This is necessary to configure the [SliverOverlapAbsorber] and
+  /// [SliverOverlapInjector] widgets.
+  ///
+  /// For sample code showing how to use this method, see the [NestedScrollView]
+  /// documentation.
   static SliverOverlapAbsorberHandle sliverOverlapAbsorberHandleFor(BuildContext context) {
     final _InheritedNestedScrollView target = context.inheritFromWidgetOfExactType(_InheritedNestedScrollView);
     assert(target != null, 'NestedScrollView.sliverOverlapAbsorberHandleFor must be called with a context that contains a NestedScrollView.');
@@ -926,9 +934,11 @@ class _NestedScrollPosition extends ScrollPosition implements ScrollActivityDele
   double applyFullDragUpdate(double delta) {
     assert(delta != 0.0);
     final double oldPixels = pixels;
+    // Apply friction:
     final double newPixels = pixels - physics.applyPhysicsToUserOffset(this, delta);
     if (oldPixels == newPixels)
       return 0.0; // delta must have been so small we dropped it during floating point addition
+    // Check for overscroll:
     final double overscroll = physics.applyBoundaryConditions(this, newPixels);
     final double actualNewPixels = newPixels - overscroll;
     if (actualNewPixels != oldPixels) {
@@ -1304,6 +1314,10 @@ class RenderSliverOverlapAbsorber extends RenderSliver with RenderObjectWithChil
     this.child = child;
   }
 
+  /// The object in which the absorbed overlap is recorded.
+  ///
+  /// A particular [SliverOverlapAbsorberHandle] can only be assigned to a
+  /// single [RenderSliverOverlapAbsorber] at a time.
   SliverOverlapAbsorberHandle get handle => _handle;
   SliverOverlapAbsorberHandle _handle;
   set handle(SliverOverlapAbsorberHandle value) {

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

@@ -67,9 +67,10 @@ class ScrollPhysics {
     return new ScrollPhysics(parent: buildParent(ancestor));
   }
 
-  /// Used by [DragScrollActivity] and other user-driven activities to
-  /// convert an offset in logical pixels as provided by the [DragUpdateDetails]
-  /// into a delta to apply using [ScrollActivityDelegate.setPixels].
+  /// Used by [DragScrollActivity] and other user-driven activities to convert
+  /// an offset in logical pixels as provided by the [DragUpdateDetails] into a
+  /// delta to apply (subtract from the current position) using
+  /// [ScrollActivityDelegate.setPixels].
   ///
   /// This is used by some [ScrollPosition] subclasses to apply friction during
   /// overscroll situations.
@@ -124,6 +125,17 @@ class ScrollPhysics {
   /// The given `position` is only valid during this method call. Do not keep a
   /// reference to it to use later, as the values may update, may not update, or
   /// may update to reflect an entirely unrelated scrollable.
+  ///
+  /// ## Examples
+  ///
+  /// [BouncingScrollPhysics] returns zero. In other words, it allows scrolling
+  /// past the boundary unhindered.
+  ///
+  /// [ClampingScrollPhysics] returns the amount by which the value is beyond
+  /// the position or the boundary, whichever is furthest from the content. In
+  /// other words, it disallows scrolling past the boundary, but allows
+  /// scrolling back from being overscrolled, if for some reason the position
+  /// ends up overscrolled.
   double applyBoundaryConditions(ScrollMetrics position, double value) {
     if (parent == null)
       return 0.0;

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

@@ -334,6 +334,9 @@ abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
   /// amount of value that cannot be applied to [pixels] as a result of the
   /// boundary conditions. If the [physics] allow out-of-bounds scrolling, this
   /// method always returns 0.0.
+  ///
+  /// The default implementation defers to the [physics] object's
+  /// [ScrollPhysics.applyBoundaryConditions].
   @protected
   double applyBoundaryConditions(double value) {
     final double result = physics.applyBoundaryConditions(this, value);

packages/flutter_tools/lib/src/compile.dart

@@ -58,9 +58,9 @@ class _StdoutHandler {
 Future<String> compile(
     {String sdkRoot,
     String mainPath,
-    bool linkPlatformKernelIn : false,
-    bool aot : false,
-    bool strongMode : false,
+    bool linkPlatformKernelIn: false,
+    bool aot: false,
+    bool strongMode: false,
     List<String> extraFrontEndOptions,
     String incrementalCompilerByteStorePath,
     String packagesPath}) async {

packages/flutter_tools/lib/src/test/flutter_platform.dart

@@ -222,9 +222,11 @@ class _FlutterPlatform extends PlatformPlugin {
 
         // copy 'vm_platform_strong.dill' into 'platform.dill'
         final File vmPlatformStrongDill = fs.file(
-            artifacts.getArtifactPath(Artifact.platformKernelStrongDill));
+          artifacts.getArtifactPath(Artifact.platformKernelStrongDill),
+        );
         final File platformDill = vmPlatformStrongDill.copySync(
-            tempBundleDirectory.childFile('platform.dill').path);
+          tempBundleDirectory.childFile('platform.dill').path,
+        );
         if (!platformDill.existsSync()) {
           printError('unexpected error copying platform kernel file');
         }

packages/flutter_tools/lib/src/test/runner.dart

@@ -43,10 +43,10 @@ Future<int> runTests(
   if (enableObservatory) {
     // (In particular, for collecting code coverage.)
 
-    // Turn on concurrency, but just barely.  If we just go with full concurrency, then
-    // individual tests timeout.  If we turn it off (=1), then the overall tests timeout.
-    // This is a lit fuse... Eventually it won't matter what number we put here.
-    // TODO(gspencer): Fix this: https://github.com/flutter/flutter/issues/10694
+    // Turn on concurrency, but just barely. This is a trade-off between running
+    // too many tests such that they all time out, and too few tests such that
+    // the tests overall take too much time. The current number is empirically
+    // based on what our infrastructure can handle, which isn't ideal...
     testArgs.add('--concurrency=2');
   }
 
@@ -96,7 +96,6 @@ Future<int> runTests(
     await test.main(testArgs);
 
     // test.main() sets dart:io's exitCode global.
-    // TODO(skybrian): restore previous value?
     printTrace('test package returned with exit code $exitCode');
 
     return exitCode;

packages/flutter_tools/test/data/asset_test/main/.gitignore

+.packages
+pubspec.lock