Merge pull request #854 from floitschG/nitpicking

Minor modifs.

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

@@ -6,12 +6,12 @@ import 'dart:ui' show Color, Size, Rect;
 
 import 'curves.dart';
 
-/// The direction in which an animation is running
+/// The direction in which an animation is running.
 enum AnimationDirection {
-  /// The animation is running from beginning to end
+  /// The animation is running from beginning to end.
   forward,
 
-  /// The animation is running backwards, from end to beginning
+  /// The animation is running backwards, from end to beginning.
   reverse
 }
 
@@ -43,12 +43,12 @@ class AnimatedValue<T extends dynamic> implements Animatable {
   /// Returns the value this variable has at the given animation clock value.
   T lerp(double t) => begin + (end - begin) * t;
 
-  /// The curve to use in the forward direction
+  /// The curve to use in the forward direction.
   Curve curve;
 
-  /// The curve to use in the reverse direction
+  /// The curve to use in the reverse direction.
   ///
-  /// If this field is null, use [curve] in both directions.
+  /// If this field is null, uses [curve] in both directions.
   Curve reverseCurve;
 
   Curve _getActiveCurve(AnimationDirection direction) {
@@ -57,7 +57,6 @@ class AnimatedValue<T extends dynamic> implements Animatable {
     return reverseCurve;
   }
 
-  /// Applies this timing to the given animation clock value in the given direction
   double transform(double t, AnimationDirection direction) {
     Curve activeCurve = _getActiveCurve(direction);
     if (activeCurve == null)
@@ -120,13 +119,11 @@ class AnimatedRectValue extends AnimatedValue<Rect> {
 }
 
 /// An animated variable containing a int.
-///
-/// The inherited lerp() function doesn't work with ints because it multiplies
-/// the begin and end types by a double, and int * double returns a double.
-/// This class overrides the lerp() function to round off the result to an int.
 class AnimatedIntValue extends AnimatedValue<int> {
   AnimatedIntValue(int begin, { int end, Curve curve, Curve reverseCurve })
     : super(begin, end: end, curve: curve, reverseCurve: reverseCurve);
 
+  // The inherited lerp() function doesn't work with ints because it multiplies
+  // the begin and end types by a double, and int * double returns a double.
   int lerp(double t) => (begin + (end - begin) * t).round();
 }

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

@@ -5,7 +5,6 @@
 import 'dart:math' as math;
 
 double _evaluateCubic(double a, double b, double m) {
-  // TODO(abarth): Would Math.pow be faster?
   return 3 * a * (1 - m) * (1 - m) * m + 3 * b * (1 - m) * m * m + m * m * m;
 }
 
@@ -15,29 +14,29 @@ const double _kCubicErrorBound = 0.001;
 ///
 /// A curve must map 0.0 to 0.0 and 1.0 to 1.0.
 abstract class Curve {
-  /// Return the value of the curve at point t
+  /// Returns the value of the curve at point [t].
   ///
-  /// The value of t must be between 0.0 and 1.0, inclusive.
+  /// The value of [t] must be between 0.0 and 1.0, inclusive.
   double transform(double t);
 }
 
-/// The identity map over the unit interval
+/// The identity map over the unit interval.
 class Linear implements Curve {
   const Linear();
   double transform(double t) => t;
 }
 
-/// A curve that is 0.0 until start, then curved from 0.0 to 1.0 at end, then 1.0
+/// A curve that is 0.0 until start, then curved from 0.0 to 1.0 at end, then 1.0.
 class Interval implements Curve {
   const Interval(this.start, this.end, { this.curve: Curves.linear });
 
-  /// The smallest value for which this interval is 0.0
+  /// The smallest value for which this interval is 0.0.
   final double start;
 
-  /// The smallest value for which this interval is 1.0
+  /// The smallest value for which this interval is 1.0.
   final double end;
 
-  /// The curve to apply between [start] and [end]
+  /// The curve to apply between [start] and [end].
   final Curve curve;
 
   double transform(double t) {
@@ -53,7 +52,7 @@ class Interval implements Curve {
   }
 }
 
-/// A cubic polynomial mapping of the unit interval
+/// A cubic polynomial mapping of the unit interval.
 class Cubic implements Curve {
   const Cubic(this.a, this.b, this.c, this.d);
 
@@ -92,7 +91,7 @@ double _bounce(double t) {
   return 7.5625 * t * t + 0.984375;
 }
 
-/// An oscillating curve that grows in magnitude
+/// An oscillating curve that grows in magnitude.
 class BounceInCurve implements Curve {
   const BounceInCurve();
   double transform(double t) {
@@ -100,7 +99,7 @@ class BounceInCurve implements Curve {
   }
 }
 
-/// An oscillating curve that shrink in magnitude
+/// An oscillating curve that shrink in magnitude.
 class BounceOutCurve implements Curve {
   const BounceOutCurve();
   double transform(double t) {
@@ -108,7 +107,7 @@ class BounceOutCurve implements Curve {
   }
 }
 
-/// An oscillating curve that first grows and then shrink in magnitude
+/// An oscillating curve that first grows and then shrink in magnitude.
 class BounceInOutCurve implements Curve {
   const BounceInOutCurve();
   double transform(double t) {
@@ -119,7 +118,7 @@ class BounceInOutCurve implements Curve {
   }
 }
 
-/// An oscillating curve that grows in magnitude while overshootings its bounds
+/// An oscillating curve that grows in magnitude while overshooting its bounds.
 class ElasticInCurve implements Curve {
   const ElasticInCurve([this.period = 0.4]);
   final double period;
@@ -130,7 +129,7 @@ class ElasticInCurve implements Curve {
   }
 }
 
-/// An oscillating curve that shrinks in magnitude while overshootings its bounds
+/// An oscillating curve that shrinks in magnitude while overshooting its bounds.
 class ElasticOutCurve implements Curve {
   const ElasticOutCurve([this.period = 0.4]);
   final double period;
@@ -140,7 +139,7 @@ class ElasticOutCurve implements Curve {
   }
 }
 
-/// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds
+/// An oscillating curve that grows and then shrinks in magnitude while overshooting its bounds.
 class ElasticInOutCurve implements Curve {
   const ElasticInOutCurve([this.period = 0.4]);
   final double period;
@@ -161,36 +160,40 @@ class Curves {
   /// A linear animation curve
   static const Linear linear = const Linear();
 
-  /// A cubic animation curve that speeds up quickly and ends slowly
+  /// A cubic animation curve that speeds up quickly and ends slowly.
   static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0);
 
-  /// A cubic animation curve that starts slowly and ends quickly
+  /// A cubic animation curve that starts slowly and ends quickly.
   static const Cubic easeIn = const Cubic(0.42, 0.0, 1.0, 1.0);
 
-  /// A cubic animation curve that starts quickly and ends slowly
+  /// A cubic animation curve that starts quickly and ends slowly.
   static const Cubic easeOut = const Cubic(0.0, 0.0, 0.58, 1.0);
 
-  /// A cubic animation curve that starts slowly, speeds up, and then and ends slowly
+  /// A cubic animation curve that starts slowly, speeds up, and then and ends slowly.
   static const Cubic easeInOut = const Cubic(0.42, 0.0, 0.58, 1.0);
 
-  /// An oscillating curve that grows in magnitude
+  /// An oscillating curve that grows in magnitude.
   static const BounceInCurve bounceIn = const BounceInCurve();
 
-  /// An oscillating curve that first grows and then shrink in magnitude
+  /// An oscillating curve that first grows and then shrink in magnitude.
   static const BounceOutCurve bounceOut = const BounceOutCurve();
 
-  /// An oscillating curve that first grows and then shrink in magnitude
+  /// An oscillating curve that first grows and then shrink in magnitude.
   static const BounceInOutCurve bounceInOut = const BounceInOutCurve();
 
-  /// An oscillating curve that grows in magnitude while overshootings its bounds
+  /// An oscillating curve that grows in magnitude while overshootings its bounds.
   static const ElasticInCurve elasticIn = const ElasticInCurve();
 
-  /// An oscillating curve that shrinks in magnitude while overshootings its bounds
+  /// An oscillating curve that shrinks in magnitude while overshootings its bounds.
   static const ElasticOutCurve elasticOut = const ElasticOutCurve();
 
-  /// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds
+  /// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds.
   static const ElasticInOutCurve elasticInOut = const ElasticInOutCurve();
 
-  /// A curve that starts quickly and eases into its final position. Over the course of the animation, the object spends more time near its final destination. As a result, the user isn’t left waiting for the animation to finish, and the negative effects of motion are minimized.
+  /// A curve that starts quickly and eases into its final position.
+  ///
+  /// Over the course of the animation, the object spends more time near its
+  /// final destination. As a result, the user isn’t left waiting for the
+  /// animation to finish, and the negative effects of motion are minimized.
   static const Curve fastOutSlowIn = const Cubic(0.4, 0.0, 0.2, 1.0);
 }

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

@@ -4,27 +4,27 @@
 
 import 'package:newton/newton.dart';
 
-/// A factory for simulations
+/// A factory for simulations.
 abstract class Force {
   const Force();
 
   Simulation release(double position, double velocity);
 }
 
-/// A factory for spring-based physics simulations
+/// A factory for spring-based physics simulations.
 class SpringForce extends Force {
   const SpringForce(this.spring, { this.left: 0.0, this.right: 1.0 });
 
-  /// The description of the spring to be used in the created simulations
+  /// The description of the spring to be used in the created simulations.
   final SpringDescription spring;
 
-  /// Where to put the spring's resting point when releasing left
+  /// Where to put the spring's resting point when releasing left.
   final double left;
 
-  /// Where to put the spring's resting point when releasing right
+  /// Where to put the spring's resting point when releasing right.
   final double right;
 
-  /// How pricely to terminate the simulation
+  /// How pricely to terminate the simulation.
   ///
   /// We overshoot the target by this distance, but stop the simulation when
   /// the spring gets within this distance (regardless of how fast it's moving).
@@ -48,5 +48,5 @@ final SpringDescription _kDefaultSpringDesc = new SpringDescription.withDampingR
   ratio: 1.0
 );
 
-/// A spring force with reasonable default values
+/// A spring force with reasonable default values.
 final SpringForce kDefaultSpringForce = new SpringForce(_kDefaultSpringDesc);

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

@@ -13,22 +13,25 @@ import 'forces.dart';
 import 'listener_helpers.dart';
 import 'simulation_stepper.dart';
 
-/// An interface that is implemented by [Performance] that exposes a
-/// read-only view of the underlying performance. This is used by classes that
+/// A read-only view of a [Performance].
+///
+/// This interface is implemented by [Performance].
+///
+/// Read-only access to [Performance] is used by classes that
 /// want to watch a performance but should not be able to change the
 /// performance's state.
 abstract class PerformanceView {
   const PerformanceView();
 
-  /// Update the given variable according to the current progress of the performance
+  /// Update the given variable according to the current progress of the performance.
   void updateVariable(Animatable variable);
-  /// Calls the listener every time the progress of the performance changes
+  /// Calls the listener every time the progress of the performance changes.
   void addListener(VoidCallback listener);
-  /// Stop calling the listener every time the progress of the performance changes
+  /// Stop calling the listener every time the progress of the performance changes.
   void removeListener(VoidCallback listener);
-  /// Calls listener every time the status of the performance changes
+  /// Calls listener every time the status of the performance changes.
   void addStatusListener(PerformanceStatusListener listener);
-  /// Stops calling the listener every time the status of the performance changes
+  /// Stops calling the listener every time the status of the performance changes.
   void removeStatusListener(PerformanceStatusListener listener);
 
   /// The current status of this animation.
@@ -45,13 +48,15 @@ abstract class PerformanceView {
   AnimationDirection get curveDirection;
 
   /// The current progress of this animation (a value from 0.0 to 1.0).
-  /// This is the value that is used to update any variables when using updateVariable().
+  ///
+  /// This is the value that is used to update any variables when using
+  /// [updateVariable].
   double get progress;
 
-  /// Whether this animation is stopped at the beginning
+  /// Whether this animation is stopped at the beginning.
   bool get isDismissed => status == PerformanceStatus.dismissed;
 
-  /// Whether this animation is stopped at the end
+  /// Whether this animation is stopped at the end.
   bool get isCompleted => status == PerformanceStatus.completed;
 
   String toString() {
@@ -556,7 +561,7 @@ class Performance extends PerformanceView
       _timeline.value = progress.clamp(0.0, 1.0);
   }
 
-  /// A label that is used in the toString() output. Intended to aid with
+  /// A label that is used in the [toString] output. Intended to aid with
   /// identifying performance instances in debug output.
   final String debugLabel;
 
@@ -565,7 +570,7 @@ class Performance extends PerformanceView
   /// allowing users of that pointer to mutate the Performance state.
   PerformanceView get view => this;
 
-  /// The length of time this performance should last
+  /// The length of time this performance should last.
   Duration duration;
 
   SimulationStepper _timeline;
@@ -574,7 +579,7 @@ class Performance extends PerformanceView
   AnimationDirection get curveDirection => _curveDirection;
   AnimationDirection _curveDirection = AnimationDirection.forward;
 
-  /// The progress of this performance along the timeline
+  /// The progress of this performance along the timeline.
   ///
   /// Note: Setting this value stops the current animation.
   double get progress => _timeline.value.clamp(0.0, 1.0);
@@ -584,7 +589,7 @@ class Performance extends PerformanceView
     _checkStatusChanged();
   }
 
-  /// Whether this animation is currently animating in either the forward or reverse direction
+  /// Whether this animation is currently animating in either the forward or reverse direction.
   bool get isAnimating => _timeline.isAnimating;
 
   PerformanceStatus get status {
@@ -597,55 +602,52 @@ class Performance extends PerformanceView
         PerformanceStatus.reverse;
   }
 
-  /// Update the given varaible according to the current progress of this performance
+  /// Updates the given variable according to the current progress of this performance.
   void updateVariable(Animatable variable) {
     variable.setProgress(progress, _curveDirection);
   }
 
-  /// Start running this animation forwards (towards the end)
+  /// Starts running this animation forwards (towards the end).
   Future forward() => play(AnimationDirection.forward);
 
-  /// Start running this animation in reverse (towards the beginning)
+  /// Starts running this animation in reverse (towards the beginning).
   Future reverse() => play(AnimationDirection.reverse);
 
-  /// Start running this animation in the given direction
+  /// Starts running this animation in the given direction.
   Future play([AnimationDirection direction = AnimationDirection.forward]) {
     _direction = direction;
     return resume();
   }
 
-  /// Start running this animation in the most recent direction
+  /// Resumes this animation in the most recent direction.
   Future resume() {
     return _animateTo(_direction == AnimationDirection.forward ? 1.0 : 0.0);
   }
 
-  /// Stop running this animation.
+  /// Stops running this animation.
   void stop() {
     _timeline.stop();
   }
 
-  /// Release any resources used by this object.
+  /// Releases any resources used by this object.
   ///
   /// Same as stop().
   void dispose() {
     stop();
   }
 
-  /// Start running this animation according to the given physical parameters
   ///
   /// Flings the timeline with an optional force (defaults to a critically
   /// damped spring) and initial velocity. If velocity is positive, the
   /// animation will complete, otherwise it will dismiss.
   Future fling({double velocity: 1.0, Force force}) {
-    if (force == null)
-      force = kDefaultSpringForce;
+    force ??= kDefaultSpringForce;
     _direction = velocity < 0.0 ? AnimationDirection.reverse : AnimationDirection.forward;
     return _timeline.animateWith(force.release(progress, velocity));
   }
 
   Future repeat({ double min: 0.0, double max: 1.0, Duration period }) {
-    if (period == null)
-      period = duration;
+    period ??= duration;
     return _timeline.animateWith(new _RepeatingSimulation(min, max, period));
   }
 
@@ -690,7 +692,7 @@ class Performance extends PerformanceView
   }
 }
 
-/// An animation performance with an animated variable with a concrete type
+/// An animation performance with an animated variable with a concrete type.
 class ValuePerformance<T> extends Performance {
   ValuePerformance({ this.variable, Duration duration, double progress }) :
     super(duration: duration, progress: progress);
@@ -707,7 +709,7 @@ class ValuePerformance<T> extends Performance {
 
 class _RepeatingSimulation extends Simulation {
   _RepeatingSimulation(this.min, this.max, Duration period)
-    : _periodInSeconds = period.inMicroseconds.toDouble() / Duration.MICROSECONDS_PER_SECOND {
+    : _periodInSeconds = period.inMicroseconds / Duration.MICROSECONDS_PER_SECOND {
     assert(_periodInSeconds > 0.0);
   }
 

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

@@ -11,15 +11,18 @@ const double _kScrollDrag = 0.025;
 
 /// An interface for controlling the behavior of scrollable widgets.
 abstract class ScrollBehavior {
-  /// Called when a drag gesture ends. Returns a simulation that
-  /// propels the scrollOffset.
+  /// Returns a simulation that propels the scrollOffset.
+  ///
+  /// This function is called when a drag gesture ends.
   Simulation createFlingScrollSimulation(double position, double velocity) => null;
 
-  /// Called when a drag gesture ends and toSnapOffset is specified.
   /// Returns an animation that ends at the snap offset.
+  ///
+  /// This function is called when a drag gesture ends and toSnapOffset is specified.
   Simulation createSnapScrollSimulation(double startOffset, double endOffset, double startVelocity, double endVelocity) => null;
 
-  /// Return the scroll offset to use when the user attempts to scroll
+
+  /// Returns the scroll offset to use when the user attempts to scroll
   /// from the given offset by the given delta.
   double applyCurve(double scrollOffset, double scrollDelta);
 
@@ -27,7 +30,7 @@ abstract class ScrollBehavior {
   bool get isScrollable => true;
 }
 
-/// A scroll behavior for a scrollable widget with linear extent
+/// A scroll behavior for a scrollable widget with linear extent.
 abstract class ExtentScrollBehavior extends ScrollBehavior {
   ExtentScrollBehavior({ double contentExtent: 0.0, double containerExtent: 0.0 })
     : _contentExtent = contentExtent, _containerExtent = containerExtent;
@@ -40,10 +43,11 @@ abstract class ExtentScrollBehavior extends ScrollBehavior {
   double get containerExtent => _containerExtent;
   double _containerExtent;
 
-  /// Update either content or container extent (or both)
+  /// Updates either content or container extent (or both)
+  ///
+  /// Returns the new scroll offset of the widget after the change in extent.
   ///
-  /// The scrollOffset parameter is the scroll offset of the widget before the
-  /// change in extent. Returns the new scroll offset of the widget after the
+  /// The [scrollOffset] parameter is the scroll offset of the widget before the
   /// change in extent.
   double updateExtents({
     double contentExtent,
@@ -64,7 +68,7 @@ abstract class ExtentScrollBehavior extends ScrollBehavior {
   double get maxScrollOffset;
 }
 
-/// A scroll behavior that prevents the user from exeeding scroll bounds.
+/// A scroll behavior that prevents the user from exceeding scroll bounds.
 class BoundedBehavior extends ExtentScrollBehavior {
   BoundedBehavior({ double contentExtent: 0.0, double containerExtent: 0.0 })
     : super(contentExtent: contentExtent, containerExtent: containerExtent);

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

@@ -9,13 +9,13 @@ import 'animated_value.dart';
 import 'curves.dart';
 import 'ticker.dart';
 
-/// A simulation that varies from [begin] to [end] over [duration] using [curve]
+/// A simulation that varies from [begin] to [end] over [duration] using [curve].
 ///
 /// This class is an adaptor between the Simulation interface and the
 /// AnimatedValue interface.
 class _TweenSimulation extends Simulation {
   _TweenSimulation(double begin, double end, Duration duration, Curve curve)
-    : _durationInSeconds = duration.inMicroseconds.toDouble() / Duration.MICROSECONDS_PER_SECOND,
+    : _durationInSeconds = duration.inMicroseconds / Duration.MICROSECONDS_PER_SECOND,
       _tween = new AnimatedValue<double>(begin, end: end, curve: curve) {
     assert(_durationInSeconds > 0.0);
     assert(begin != null);
@@ -49,7 +49,7 @@ class SimulationStepper {
   Ticker _ticker;
   Simulation _simulation;
 
-  /// The current value of the timeline
+  /// The current value of the timeline.
   double get value => _value;
   double _value = 0.0;
   void set value(double newValue) {
@@ -59,10 +59,10 @@ class SimulationStepper {
     _onTick(_value);
   }
 
-  /// Whether the timeline is currently animating
+  /// Whether the timeline is currently animating.
   bool get isAnimating => _ticker.isTicking;
 
-  /// Animate value of the timeline to the given target over the given duration
+  /// Animates value of the timeline to the given target over the given duration.
   ///
   /// Returns a future that resolves when the timeline stops animating,
   /// typically when the timeline arives at the target value.
@@ -72,13 +72,13 @@ class SimulationStepper {
     return _start(new _TweenSimulation(value, target, duration, curve));
   }
 
-  /// Gives the given simulation control over the timeline
+  /// Gives the given simulation control over the timeline.
   Future animateWith(Simulation simulation) {
     stop();
     return _start(simulation);
   }
 
-  /// Start ticking the given simulation once per frame
+  /// Starts ticking the given simulation once per frame.
   ///
   /// Returns a future that resolves when the simulation stops ticking.
   Future _start(Simulation simulation) {
@@ -89,7 +89,7 @@ class SimulationStepper {
     return _ticker.start();
   }
 
-  /// Stop animating the timeline
+  /// Stops animating the timeline.
   void stop() {
     _simulation = null;
     _ticker.stop();

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

@@ -8,7 +8,7 @@ import 'scheduler.dart';
 
 typedef TickerCallback(Duration elapsed);
 
-/// Calls its callback once per animation frame
+/// Calls its callback once per animation frame.
 class Ticker {
   /// Constructs a ticker that will call onTick once per frame while running
   Ticker(TickerCallback onTick) : _onTick = onTick;
@@ -19,7 +19,7 @@ class Ticker {
   int _animationId;
   Duration _startTime;
 
-  /// Start calling onTick once per animation frame
+  /// Starts calling onTick once per animation frame.
   ///
   /// The returned future resolves once the ticker stops ticking.
   Future start() {
@@ -30,7 +30,7 @@ class Ticker {
     return _completer.future;
   }
 
-  /// Stop calling onTick
+  /// Stops calling onTick.
   ///
   /// Causes the future returned by [start] to resolve.
   void stop() {

packages/flutter/lib/src/gestures/arena.dart

@@ -23,7 +23,7 @@ abstract class GestureArenaMember {
   void rejectGesture(Object key);
 }
 
-/// An interface to information to an arena
+/// An interface to information to an arena.
 ///
 /// A given [GestureArenaMember] can have multiple entries in multiple arenas
 /// with different keys.
@@ -80,7 +80,7 @@ class GestureArena {
     _tryToResolveArena(key, state);
   }
 
-  /// Force resolution on this arena, giving the win to the first member
+  /// Forces resolution on this arena, giving the win to the first member.
   void sweep(Object key) {
     _GestureArenaState state = _arenas[key];
     if (state == null)
@@ -100,7 +100,7 @@ class GestureArena {
     }
   }
 
-  /// Prevent the arena from being swept
+  /// Prevents the arena from being swept.
   void hold(Object key) {
     _GestureArenaState state = _arenas[key];
     if (state == null)
@@ -108,9 +108,10 @@ class GestureArena {
     state.isHeld = true;
   }
 
-  /// Release a hold, allowing the arena to be swept
+  /// Releases a hold, allowing the arena to be swept.
+  ///
   /// If a sweep was attempted on a held arena, the sweep will be done
-  /// on release
+  /// on release.
   void release(Object key) {
     _GestureArenaState state = _arenas[key];
     if (state == null)

packages/flutter/lib/src/gestures/lsq_solver.dart

@@ -101,12 +101,12 @@ class LeastSquaresSolver {
   final List<double> w;
 
   PolynomialFit solve(int degree) {
-    if (degree > x.length) // not enough data to fit a curve
+    if (degree > x.length) // Not enough data to fit a curve.
       return null;
 
     PolynomialFit result = new PolynomialFit(degree);
 
-    // Shorthands for the purpose of notation equivalence to original C++ code
+    // Shorthands for the purpose of notation equivalence to original C++ code.
     final int m = x.length;
     final int n = degree + 1;
 
@@ -135,7 +135,7 @@ class LeastSquaresSolver {
 
       double norm = q.getRow(j).norm();
       if (norm < 0.000001) {
-        // vectors are linearly dependent or zero so no solution
+        // Vectors are linearly dependent or zero so no solution.
         return null;
       }
 

packages/flutter/lib/src/gestures/multitap.dart

@@ -91,7 +91,7 @@ class DoubleTapGestureRecognizer extends GestureRecognizer {
   final Map<int, _TapTracker> _trackers = new Map<int, _TapTracker>();
 
   void addPointer(PointerEvent event) {
-    // Ignore out-of-bounds second taps
+    // Ignore out-of-bounds second taps.
     if (_firstTap != null &&
         !_firstTap.isWithinTolerance(event, kDoubleTapSlop))
       return;
@@ -155,7 +155,7 @@ class DoubleTapGestureRecognizer extends GestureRecognizer {
     _stopDoubleTapTimer();
     if (_firstTap != null) {
       // Note, order is important below in order for the resolve -> reject logic
-      // to work properly
+      // to work properly.
       _TapTracker tracker = _firstTap;
       _firstTap = null;
       _reject(tracker);

packages/flutter/lib/src/gestures/pointer_router.dart

@@ -34,7 +34,7 @@ class PointerRouter {
       _routeMap.remove(pointer);
   }
 
-  /// Call the routes registed for this pointer event.
+  /// Calls the routes registed for this pointer event.
   ///
   /// Calls the routes in the order in which they were added to the route.
   void route(PointerEvent event) {

packages/flutter/lib/src/gestures/recognizer.dart

@@ -14,15 +14,17 @@ export 'pointer_router.dart' show PointerRouter;
 
 abstract class GestureRecognizer extends GestureArenaMember {
 
-  /// Call this with the pointerdown event of each pointer that should be
-  /// considered for this gesture. (It's the GestureRecognizer's responsibility
-  /// to then add itself to the global pointer router to receive subsequent
-  /// events for this pointer.)
+  /// Calls this with the pointerdown event of each pointer that should be
+  /// considered for this gesture.
+  ///
+  /// It's the GestureRecognizer's responsibility to then add itself to the
+  /// global pointer router to receive subsequent events for this pointer.
   void addPointer(PointerDownEvent event);
 
-  /// Release any resources used by the object. Called when the object is no
-  /// longer needed (e.g. a gesture recogniser is being unregistered from a
-  /// [GestureDetector]).
+  /// Releases any resources used by the object.
+  ///
+  /// This method is called when the object is no longer needed (e.g. a gesture
+  /// recogniser is being unregistered from a [GestureDetector]).
   void dispose() { }
 
 }
@@ -123,7 +125,7 @@ abstract class PrimaryPointerGestureRecognizer extends OneSequenceGestureRecogni
   /// Override to provide behavior for the primary pointer when the gesture is still possible.
   void handlePrimaryPointer(PointerEvent event);
 
-  /// Override to be notified with [deadline] is exceeded.
+  /// Override to be notified when [deadline] is exceeded.
   ///
   /// You must override this function if you supply a [deadline].
   void didExceedDeadline() {

packages/flutter/lib/src/http/http.dart

@@ -2,9 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/// A [Future]-based library for making HTTP requests. It's based on
-/// Dart's `http` package, but we've removed the dependency on mirrors
-/// and added a `mojo`-based HTTP client.
+/// A [Future]-based library for making HTTP requests.
+///
+/// Let library is based on Dart's `http` package, but we have removed the
+/// dependency on mirrors and added a `mojo`-based HTTP client.
 library http;
 
 import 'dart:async';

packages/flutter/lib/src/http/mojo_client.dart

@@ -16,7 +16,7 @@ import 'package:mojo/mojo/http_header.mojom.dart' as mojo;
 
 import 'response.dart';
 
-/// A `mojo`-based HTTP client
+/// A `mojo`-based HTTP client.
 class MojoClient {
 
   Future<Response> head(url, {Map<String, String> headers}) =>

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

@@ -8,7 +8,7 @@ import 'dart:ui' as ui;
 class ShadowDrawLooperBuilder {
   ui.LayerDrawLooperBuilder _builder = new ui.LayerDrawLooperBuilder();
 
-  /// Add a shadow with the given parameters
+  /// Adds a shadow with the given parameters.
   void addShadow(ui.Offset offset, ui.Color color, double blur) {
     _builder.addLayerOnTop(
       new ui.DrawLooperLayerInfo()

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

@@ -7,21 +7,21 @@ import 'dart:ui' as ui;
 import 'basic_types.dart';
 import 'text_style.dart';
 
-/// An immutable span of text
+/// An immutable span of text.
 abstract class TextSpan {
-  // This class must be immutable, because we won't notice when it changes
+  // This class must be immutable, because we won't notice when it changes.
   String toString([String prefix = '']);
   void build(ui.ParagraphBuilder builder);
   ui.ParagraphStyle get paragraphStyle => null;
 }
 
-/// An immutable span of unstyled text
+/// An immutable span of unstyled text.
 class PlainTextSpan extends TextSpan {
   PlainTextSpan(this.text) {
     assert(text != null);
   }
 
-  /// The text contained in the span
+  /// The text contained in the span.
   final String text;
 
   void build(ui.ParagraphBuilder builder) {
@@ -40,17 +40,17 @@ class PlainTextSpan extends TextSpan {
   String toString([String prefix = '']) => '$prefix$runtimeType: "$text"';
 }
 
-/// An immutable text span that applies a style to a list of children
+/// An immutable text span that applies a style to a list of children.
 class StyledTextSpan extends TextSpan {
   StyledTextSpan(this.style, this.children) {
     assert(style != null);
     assert(children != null);
   }
 
-  /// The style to apply to the children
+  /// The style to apply to the children.
   final TextStyle style;
 
-  /// The children to which the style is applied
+  /// The children to which the style is applied.
   final List<TextSpan> children;
 
   void build(ui.ParagraphBuilder builder) {
@@ -97,7 +97,7 @@ class StyledTextSpan extends TextSpan {
   }
 }
 
-/// An object that paints a [TextSpan] into a canvas
+/// An object that paints a [TextSpan] into a canvas.
 class TextPainter {
   TextPainter(TextSpan text) {
     this.text = text;
@@ -107,7 +107,7 @@ class TextPainter {
   bool _needsLayout = true;
 
   TextSpan _text;
-  /// The (potentially styled) text to paint
+  /// The (potentially styled) text to paint.
   TextSpan get text => _text;
   void set text(TextSpan value) {
     if (_text == value)
@@ -119,7 +119,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// The minimum width at which to layout the text
+  /// The minimum width at which to layout the text.
   double get minWidth => _paragraph.minWidth;
   void set minWidth(value) {
     if (_paragraph.minWidth == value)
@@ -128,7 +128,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// The maximum width at which to layout the text
+  /// The maximum width at which to layout the text.
   double get maxWidth => _paragraph.maxWidth;
   void set maxWidth(value) {
     if (_paragraph.maxWidth == value)
@@ -137,7 +137,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// The minimum height at which to layout the text
+  /// The minimum height at which to layout the text.
   double get minHeight => _paragraph.minHeight;
   void set minHeight(value) {
     if (_paragraph.minHeight == value)
@@ -146,7 +146,7 @@ class TextPainter {
     _needsLayout = true;
   }
 
-  /// The maximum height at which to layout the text
+  /// The maximum height at which to layout the text.
   double get maxHeight => _paragraph.maxHeight;
   void set maxHeight(value) {
     if (_paragraph.maxHeight == value)
@@ -165,13 +165,13 @@ class TextPainter {
     return layoutValue.ceilToDouble();
   }
 
-  /// The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds
+  /// The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds.
   double get minIntrinsicWidth {
     assert(!_needsLayout);
     return _applyFloatingPointHack(_paragraph.minIntrinsicWidth);
   }
 
-  /// The width at which increasing the width of the text no longer decreases the height
+  /// The width at which increasing the width of the text no longer decreases the height.
   double get maxIntrinsicWidth {
     assert(!_needsLayout);
     return _applyFloatingPointHack(_paragraph.maxIntrinsicWidth);
@@ -192,7 +192,7 @@ class TextPainter {
     return new Size(width, height);
   }
 
-  /// The distance from the top of the text to the first baseline of the given type
+  /// Returns the distance from the top of the text to the first baseline of the given type.
   double computeDistanceToActualBaseline(TextBaseline baseline) {
     assert(!_needsLayout);
     switch (baseline) {
@@ -203,7 +203,7 @@ class TextPainter {
     }
   }
 
-  /// Compute the visual position of the glyphs for painting the text
+  /// Computes the visual position of the glyphs for painting the text.
   void layout() {
     if (!_needsLayout)
       return;
@@ -211,7 +211,7 @@ class TextPainter {
     _needsLayout = false;
   }
 
-  /// Paint the text onto the given canvas at the given offset
+  /// Paints the text onto the given canvas at the given offset.
   void paint(ui.Canvas canvas, ui.Offset offset) {
     assert(!_needsLayout && "Please call layout() before paint() to position the text before painting it." is String);
     _paragraph.paint(canvas, offset);

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

@@ -6,7 +6,7 @@ import 'dart:ui' as ui;
 
 import 'basic_types.dart';
 
-/// An immutable style in which paint text
+/// An immutable style in which paint text.
 class TextStyle {
   const TextStyle({
     this.inherit: true,

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

@@ -11,13 +11,13 @@ import 'basic_types.dart';
 class MatrixUtils {
   MatrixUtils._();
 
-  /// If the given transform is nothing but a 2D translation, then returns that
-  /// translation as an Offset.
+  /// Returns the given [transform] matrix as Offset, if the matrix is nothing
+  /// but a 2D translation.
   ///
-  /// Otherwise, returns null.
+  /// Returns null, otherwise.
   static Offset getAsTranslation(Matrix4 transform) {
     Float64List values = transform.storage;
-    // values are stored in column-major order
+    // Values are stored in column-major order.
     if (values[0] == 1.0 &&
         values[1] == 0.0 &&
         values[2] == 0.0 &&
@@ -37,4 +37,4 @@ class MatrixUtils {
     return null;
   }
 
-}
\ No newline at end of file
+}

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

@@ -10,10 +10,10 @@ import 'object.dart';
 /// Hosts the edge parameters and vends useful methods to construct expressions
 /// for constraints. Also sets up and manages implicit constraints and edit
 /// variables. Used as a mixin by layout containers and parent data instances
-/// of render boxes taking part in auto layout
+/// of render boxes taking part in auto layout.
 abstract class _AutoLayoutParamMixin {
   // Ideally, the edges would all be final, but then they would have to be
-  // initialized before the constructor. Not sure how to do that using a Mixin
+  // initialized before the constructor. Not sure how to do that using a Mixin.
   al.Param _leftEdge;
   al.Param _rightEdge;
   al.Param _topEdge;
@@ -55,9 +55,11 @@ abstract class _AutoLayoutParamMixin {
     solver.suggestValueForVariable(_rightEdge.variable, size.width);
   }
 
-  /// Called when the solver has updated at least one of the layout parameters
-  /// of this object. The object is now responsible for applying this update to
-  /// it other properties (if necessary)
+  /// Applies the parameter updates.
+  ///
+  /// This method is called when the solver has updated at least one of the
+  /// layout parameters of this object. The object is now responsible for
+  /// applying this update to its other properties (if necessary).
   void _applyAutolayoutParameterUpdates();
 
   /// Returns the set of implicit constraints that need to be applied to all
@@ -139,7 +141,7 @@ class RenderAutoLayout extends RenderBox
   List<al.Constraint> _explicitConstraints = new List<al.Constraint>();
 
   /// Adds all the given constraints to the solver. Either all constraints are
-  /// added or none
+  /// added or none.
   al.Result addConstraints(List<al.Constraint> constraints) {
     al.Result result = _solver.addConstraints(constraints);
     if (result == al.Result.success) {
@@ -149,7 +151,7 @@ class RenderAutoLayout extends RenderBox
     return result;
   }
 
-  /// Add the given constraint to the solver.
+  /// Adds the given constraint to the solver.
   al.Result addConstraint(al.Constraint constraint) {
     al.Result result = _solver.addConstraint(constraint);
 

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

@@ -22,7 +22,7 @@ typedef void MetricListener(Size size);
 class _PointerState {
   _PointerState(this.lastPosition);
 
-  int get pointer => _pointer; // the identifier used in PointerEvent objects
+  int get pointer => _pointer; // The identifier used in PointerEvent objects.
   int _pointer;
   static int _pointerCount = 0;
   void startNewPointer() {
@@ -45,7 +45,7 @@ class _PointerState {
 }
 
 class _PointerEventConverter {
-  // map from platform pointer identifiers to PointerEvent pointer identifiers
+  // Map from platform pointer identifiers to PointerEvent pointer identifiers.
   static Map<int, _PointerState> _pointers = <int, _PointerState>{};
 
   static Iterable<PointerEvent> expand(Iterable<Pointer> packet) sync* {
@@ -201,7 +201,7 @@ class BindingObserver {
   void didChangeLocale(ui.Locale locale) { }
 }
 
-/// The glue between the render tree and the Flutter engine
+/// The glue between the render tree and the Flutter engine.
 class FlutterBinding extends HitTestTarget {
 
   FlutterBinding({ RenderBox root: null, RenderView renderViewOverride }) {
@@ -227,11 +227,11 @@ class FlutterBinding extends HitTestTarget {
     assert(_instance == this);
   }
 
-  /// The singleton instance of the binding
+  /// The singleton instance of the binding.
   static FlutterBinding get instance => _instance;
   static FlutterBinding _instance;
 
-  /// The render tree that's attached to the output surface
+  /// The render tree that's attached to the output surface.
   RenderView get renderView => _renderView;
   RenderView _renderView;
 
@@ -260,7 +260,7 @@ class FlutterBinding extends HitTestTarget {
     beginFrame();
   }
 
-  /// Pump the rendering pipeline to generate a frame for the given time stamp
+  /// Pump the rendering pipeline to generate a frame for the given time stamp.
   void beginFrame() {
     RenderObject.flushLayout();
     _renderView.updateCompositingBits();
@@ -287,12 +287,13 @@ class FlutterBinding extends HitTestTarget {
       _handlePointerEvent(event);
   }
 
-  /// A router that routes all pointer events received from the engine
+  /// A router that routes all pointer events received from the engine.
   final PointerRouter pointerRouter = new PointerRouter();
 
   /// State for all pointers which are currently down.
+  ///
   /// The state of hovering pointers is not tracked because that would require
-  /// hit-testing on every fram.e
+  /// hit-testing on every frame.
   Map<int, HitTestResult> _hitTests = <int, HitTestResult>{};
 
   void _handlePointerEvent(PointerEvent event) {
@@ -312,7 +313,7 @@ class FlutterBinding extends HitTestTarget {
     }
   }
 
-  /// Determine which [HitTestTarget] objects are located at a given position
+  /// Determine which [HitTestTarget] objects are located at a given position.
   HitTestResult hitTest(Point position) {
     HitTestResult result = new HitTestResult();
     _renderView.hitTest(result, position: position);
@@ -337,12 +338,12 @@ class FlutterBinding extends HitTestTarget {
   }
 }
 
-/// Prints a textual representation of the entire render tree
+/// Prints a textual representation of the entire render tree.
 void debugDumpRenderTree() {
   debugPrint(FlutterBinding.instance.renderView.toStringDeep());
 }
 
-/// Prints a textual representation of the entire layer tree
+/// Prints a textual representation of the entire layer tree.
 void debugDumpLayerTree() {
   debugPrint(FlutterBinding.instance.renderView.layer.toStringDeep());
 }

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

@@ -9,21 +9,21 @@ import 'package:vector_math/vector_math_64.dart';
 import 'box.dart';
 import 'object.dart';
 
-/// Parent data for use with [RenderBlockBase]
+/// Parent data for use with [RenderBlockBase].
 class BlockParentData extends ContainerBoxParentDataMixin<RenderBox> { }
 
-/// The direction in which the block should lay out
+/// The direction in which the block should lay out.
 enum BlockDirection {
-  /// Children are arranged horizontally, from left to right
+  /// Children are arranged horizontally, from left to right.
   horizontal,
-  /// Children are arranged vertically, from top to bottom
+  /// Children are arranged vertically, from top to bottom.
   vertical
 }
 
 typedef double _ChildSizingFunction(RenderBox child, BoxConstraints constraints);
 typedef double _Constrainer(double value);
 
-/// Implements the block layout algorithm
+/// Implements the block layout algorithm.
 ///
 /// In block layout, children are arranged linearly along the main axis (either
 /// horizontally or vertically). In the cross axis, children are stretched to
@@ -49,7 +49,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin
       child.parentData = new BlockParentData();
   }
 
-  /// The direction to use as the main axis
+  /// The direction to use as the main axis.
   BlockDirection get direction => _direction;
   BlockDirection _direction;
   void set direction (BlockDirection value) {
@@ -59,7 +59,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin
     }
   }
 
-  /// If non-null, forces children to be exactly this large in the main axis
+  /// If non-null, forces children to be exactly this large in the main axis.
   double get itemExtent => _itemExtent;
   double _itemExtent;
   void set itemExtent(double value) {
@@ -69,7 +69,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin
     }
   }
 
-  /// Forces the block to be at least this large in the main-axis
+  /// Forces the block to be at least this large in the main-axis.
   double get minExtent => _minExtent;
   double _minExtent;
   void set minExtent(double value) {
@@ -79,7 +79,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin
     }
   }
 
-  /// Whether the main axis is vertical
+  /// Whether the main axis is vertical.
   bool get isVertical => _direction == BlockDirection.vertical;
 
   BoxConstraints _getInnerConstraints(BoxConstraints constraints) {
@@ -124,7 +124,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin
   }
 }
 
-/// A block layout with a concrete set of children
+/// A block layout with a concrete set of children.
 class RenderBlock extends RenderBlockBase {
 
   RenderBlock({
@@ -214,7 +214,7 @@ class RenderBlock extends RenderBlockBase {
 
   void performLayout() {
     assert((isVertical ? constraints.maxHeight >= double.INFINITY : constraints.maxWidth >= double.INFINITY) &&
-           'RenderBlock does not clip or resize its children, so it must be placed in a parent that does not constrain ' +
+           'RenderBlock does not clip or resize its children, so it must be placed in a parent that does not constrain '
            'the block\'s main direction. You probably want to put the RenderBlock inside a RenderViewport.' is String);
     super.performLayout();
   }
@@ -229,7 +229,7 @@ class RenderBlock extends RenderBlockBase {
 
 }
 
-/// A block layout whose children depend on its layout
+/// A block layout whose children depend on its layout.
 ///
 /// This class invokes a callbacks for layout and intrinsic dimensions. The main
 /// [callback] (constructor argument and property) is expected to modify the
@@ -261,7 +261,7 @@ class RenderBlockViewport extends RenderBlockBase {
   bool _inCallback = false;
   bool get hasLayer => true;
 
-  /// Called during [layout] to determine the blocks children
+  /// Called during [layout] to determine the blocks children.
   ///
   /// Typically the callback will mutate the child list appropriately, for
   /// example so the child list contains only visible children.
@@ -275,7 +275,7 @@ class RenderBlockViewport extends RenderBlockBase {
     markNeedsLayout();
   }
 
-  /// Returns the total main-axis extent of all the children that could be included by [callback] in one go
+  /// Returns the total main-axis extent of all the children that could be included by [callback] in one go.
   ExtentCallback get totalExtentCallback => _totalExtentCallback;
   ExtentCallback _totalExtentCallback;
   void set totalExtentCallback(ExtentCallback value) {
@@ -286,7 +286,7 @@ class RenderBlockViewport extends RenderBlockBase {
     markNeedsLayout();
   }
 
-  /// Returns the minimum cross-axis extent across all the children that could be included by [callback] in one go
+  /// Returns the minimum cross-axis extent across all the children that could be included by [callback] in one go.
   ExtentCallback get minCrossAxisExtentCallback => _minCrossAxisExtentCallback;
   ExtentCallback _minCrossAxisExtentCallback;
   void set minCrossAxisExtentCallback(ExtentCallback value) {
@@ -297,7 +297,7 @@ class RenderBlockViewport extends RenderBlockBase {
     markNeedsLayout();
   }
 
-  /// Returns the maximum cross-axis extent across all the children that could be included by [callback] in one go
+  /// Returns the maximum cross-axis extent across all the children that could be included by [callback] in one go.
   ExtentCallback get maxCrossAxisExtentCallback => _maxCrossAxisExtentCallback;
   ExtentCallback _maxCrossAxisExtentCallback;
   void set maxCrossAxisExtentCallback(ExtentCallback value) {
@@ -329,7 +329,7 @@ class RenderBlockViewport extends RenderBlockBase {
     _overlayPainter?.detach();
   }
 
-  /// The offset at which to paint the first child
+  /// The offset at which to paint the first child.
   ///
   /// Note: you can modify this property from within [callback], if necessary.
   double get startOffset => _startOffset;
@@ -354,10 +354,7 @@ class RenderBlockViewport extends RenderBlockBase {
     try {
       _inCallback = true;
       result = intrinsicCallback(constraints);
-      if (result == null)
-        result = constrainer(0.0);
-      else
-        result = constrainer(result);
+      result = constrainer(result ?? 0.0);
     } finally {
       _inCallback = false;
     }