Merge pull request #1310 from vlidholt/master

Adds documentation and cleans up code

packages/flutter_sprites/lib/action_spline.dart

@@ -17,13 +17,25 @@ Point _cardinalSplineAt(Point p0, Point p1, Point p2, Point p3, double tension,
   return new Point(x, y);
 }
 
+/// The spline action is used to animate a point along a spline definied by
+/// a set of points.
 class ActionSpline extends ActionInterval {
+
+  /// Creates a new spline action with a set of points. The [setter] is a
+  /// callback for setting the positions, [points] define the spline, and
+  /// [duration] is the time for the action to complete. Optionally a [curve]
+  /// can be used for easing.
   ActionSpline(this.setter, this.points, double duration, [Curve curve]) : super(duration, curve) {
     _dt = 1.0 / (points.length - 1.0);
   }
 
+  /// The callback used to update a point when the action is run.
   final Function setter;
+
+  /// A list of points that define the spline.
   final List<Point> points;
+
+  /// The tension of the spline, defines the roundness of the curve.
   double tension = 0.5;
 
   double _dt;

packages/flutter_sprites/lib/constraint.dart

 part of skysprites;
 
+/// A constraint limits or otherwise controls a [Node]'s properties, such as
+/// position or rotation. Add a list of constraints by setting the [Node]'s
+/// constraints property.
+///
+/// Constrains are applied after the update calls are
+/// completed. They can also be applied at any time by calling a [Node]'s
+/// [applyConstraints] method. It's possible to create custom constraints by
+/// overriding this class and implementing the [constrain] method.
 abstract class Constraint {
+  /// Called before the node's update method is called. This method can be
+  /// overridden to create setup work that needs to happen before the the
+  /// node is updated, e.g. to calculate the node's speed.
   void preUpdate(Node node, double dt) {
   }
 
+  /// Called after update is complete, if the constraint has been added to a
+  /// [Node]. Override this method to modify the node's property according to
+  /// the constraint.
   void constrain(Node node, double dt);
 }
 
@@ -19,10 +33,17 @@ double _dampenRotation(double src, double dst, double dampening) {
   return src + delta;
 }
 
+/// A [Constraint] that aligns a nodes rotation to its movement.
 class ConstraintRotationToMovement extends Constraint {
+  /// Creates a new constraint the aligns a nodes rotation to its movement
+  /// vector. A [baseRotation] and [dampening] can optionally be set.
   ConstraintRotationToMovement({this.baseRotation: 0.0, this.dampening});
 
+  /// The filter factor used when constraining the rotation of the node. Valid
+  /// values are in the range 0.0 to 1.0
   final double dampening;
+
+  /// The base rotation will be added to a the movement vectors rotation.
   final double baseRotation;
 
   Point _lastPosition;
@@ -43,11 +64,23 @@ class ConstraintRotationToMovement extends Constraint {
   }
 }
 
+/// A [Constraint] that rotates a node to point towards another node. The target
+/// node is allowed to have a different parent, but they must be in the same
+/// [SpriteBox].
 class ConstraintRotationToNode extends Constraint {
+  /// Creates a new [Constraint] that rotates the node towards the [targetNode].
+  /// The [baseRotation] will be added to the nodes rotation, and [dampening]
+  /// can be used to ease the rotation.
   ConstraintRotationToNode(this.targetNode, {this.baseRotation: 0.0, this.dampening});
 
+  /// The node to rotate towards.
   final Node targetNode;
+
+  /// The base rotation will be added after the target rotation is calculated.
   final double baseRotation;
+
+  /// The filter factor used when constraining the rotation of the node. Valid
+  /// values are in the range 0.0 to 1.0
   final double dampening;
 
   void constrain(Node node, double dt) {
@@ -71,7 +104,13 @@ class ConstraintRotationToNode extends Constraint {
   }
 }
 
+/// A [Constraint] that constrains the position of a node to equal the position
+/// of another node, optionally with dampening.
 class ConstraintPositionToNode extends Constraint {
+  /// Creates a new [Constraint] that constrains the poistion of a node to be
+  /// equal to the position of the [targetNode]. Optionally an [offset] can
+  /// be used and also [dampening]. The targetNode doesn't need to have the
+  /// same parent, but they need to be added to the same [SpriteBox].
   ConstraintPositionToNode(this.targetNode, {this.dampening, this.offset: Offset.zero});
 
   final Node targetNode;

packages/flutter_sprites/lib/label.dart

 part of skysprites;
 
+/// Labels are used to display a string of text in a the node tree. To align
+/// the label, the textAlign property of teh [TextStyle] can be set.
 class Label extends Node {
-
+  /// Creates a new Label with the provided [_text] and [_textStyle].
   Label(this._text, [this._textStyle]) {
     if (_textStyle == null) {
       _textStyle = new TextStyle();
@@ -10,6 +12,7 @@ class Label extends Node {
 
   String _text;
 
+  /// The text being drawn by the label.
   String get text => _text;
 
   set text(String text) {
@@ -19,6 +22,7 @@ class Label extends Node {
 
   TextStyle _textStyle;
 
+  /// The style to draw the text in.
   TextStyle get textStyle => _textStyle;
 
   set textStyle(TextStyle textStyle) {

packages/flutter_sprites/lib/node.dart

@@ -78,6 +78,8 @@ class Node {
 
   List<Constraint> _constraints;
 
+  /// A [List] of [Constraint]s that will be applied to the node.
+  /// The constraints are applied after the [update] method has been called.
   List<Constraint> get constraints {
     return _constraints;
   }
@@ -87,6 +89,9 @@ class Node {
     if (_spriteBox != null) _spriteBox._constrainedNodes = null;
   }
 
+  /// Called to apply the [constraints] to the node. Normally, this method is
+  /// called automatically by the [SpriteBox], but it can be called manually
+  /// if the constraints need to be applied immediately.
   void applyConstraints(double dt) {
     if (_constraints == null) return;
 

packages/flutter_sprites/lib/util.dart

@@ -5,18 +5,22 @@ math.Random _random = new math.Random();
 
 // Random methods
 
+/// Returns a random [double] in the range of 0.0 to 1.0.
 double randomDouble() {
   return _random.nextDouble();
 }
 
+/// Returns a random [double] in the range of -1.0 to 1.0.
 double randomSignedDouble() {
   return _random.nextDouble() * 2.0 - 1.0;
 }
 
+/// Returns a random [int] from 0 to max - 1.
 int randomInt(int max) {
   return _random.nextInt(max);
 }
 
+/// Returns either [true] or [false] in a most random fashion.
 bool randomBool() {
   return _random.nextDouble() < 0.5;
 }
@@ -54,9 +58,13 @@ class _Atan2Constants {
   final Float64List nnx = new Float64List(size + 1);
 }
 
+/// Provides convenience methods for calculations often carried out in graphics.
+/// Some of the methods are returning approximations.
 class GameMath {
   static final _Atan2Constants _atan2 = new _Atan2Constants();
 
+  /// Returns the angle of two vector components. The result is less acurate
+  /// than the standard atan2 function in the math package.
   static double atan2(double y, double x) {
     if (x >= 0) {
       if (y >= 0) {
@@ -85,7 +93,9 @@ class GameMath {
     }
   }
 
-  static double pointQuickDist(Point a, Point b) {
+  /// Approximates the distance between two points. The returned value can be
+  /// up to 6% wrong in the worst case.
+  static double distanceBetweenPoints(Point a, Point b) {
     double dx = a.x - b.x;
     double dy = a.y - b.y;
     if (dx < 0.0) dx = -dx;
@@ -98,20 +108,26 @@ class GameMath {
     }
   }
 
+  /// Interpolates a [double] between [a] and [b] according to the
+  /// [filterFactor], which should be in the range of 0.0 to 1.0.
   static double filter (double a, double b, double filterFactor) {
       return (a * (1-filterFactor)) + b * filterFactor;
   }
 
+  /// Interpolates a [Point] between [a] and [b] according to the
+  /// [filterFactor], which should be in the range of 0.0 to 1.0.
   static Point filterPoint(Point a, Point b, double filterFactor) {
     return new Point(filter(a.x, b.x, filterFactor), filter(a.y, b.y, filterFactor));
   }
 
-  static Point lineIntersection(Point p, Point p2, Point q, Point q2) {
+  /// Returns the intersection between two line segmentss defined by p0, p1 and
+  /// q0, q1. If the lines are not intersecting null is returned.
+  static Point lineIntersection(Point p0, Point p1, Point q0, Point q1) {
     double epsilon = 1e-10;
 
-    Vector2 r = new Vector2(p2.x - p.x, p2.y - p.y);
-    Vector2 s = new Vector2(q2.x - q.x, q2.y - q.y);
-    Vector2 qp = new Vector2(q.x - p.x, q.y - p.y);
+    Vector2 r = new Vector2(p1.x - p0.x, p1.y - p0.y);
+    Vector2 s = new Vector2(q1.x - q0.x, q1.y - q0.y);
+    Vector2 qp = new Vector2(q0.x - p0.x, q0.y - p0.y);
 
     double rxs = cross2(r, s);
 
@@ -124,7 +140,7 @@ class GameMath {
     double u = cross2(qp, r) / rxs;
 
     if ((0.0 <= t && t <= 1.0) && (0.0 <= u && u <= 1.0)) {
-      return new Point(p.x + t * r.x, p.y + t * r.y);
+      return new Point(p0.x + t * r.x, p0.y + t * r.y);
     }
 
     // No intersection between the lines