Adds missing Flutter Sprites API docs and improved README (#4022)

packages/flutter_sprites/lib/src/action.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
+/// Signature for callbacks used by the [ActionCallFunction].
 typedef void ActionCallback();
 
 /// Actions are used to animate properties of nodes or any other type of
@@ -34,19 +39,21 @@ abstract class Action {
     _finished = false;
   }
 
+  /// The total time it will take to complete the action, in seconds.
   double get duration => 0.0;
 }
 
+/// Signature for callbacks for setting properties, used by [ActionTween].
 typedef void SetterCallback(dynamic value);
 
 /// The abstract class for an action that changes properties over a time
 /// interval, optionally using an easing curve.
 abstract class ActionInterval extends Action {
+
+  /// Creates a new ActionInterval, typically you will want to pass in a
+  /// [duration] to specify how long time the action will take to complete.
   ActionInterval([this._duration = 0.0, this.curve]);
 
-  /// The duration, in seconds, of the action.
-  ///
-  ///     double myTime = myAction.duration;
   @override
   double get duration => _duration;
   double _duration;
@@ -84,9 +91,13 @@ abstract class ActionInterval extends Action {
   }
 }
 
-/// An action that repeats an action a fixed number of times.
+/// An action that repeats another action a fixed number of times.
 class ActionRepeat extends ActionInterval {
+
+  /// The number of times the [action] is repeated.
   final int numRepeats;
+
+  /// The action that is repeated.
   final ActionInterval action;
   int _lastFinishedRepeat = -1;
 
@@ -119,6 +130,8 @@ class ActionRepeat extends ActionInterval {
 
 /// An action that repeats an action an indefinite number of times.
 class ActionRepeatForever extends Action {
+
+  /// The action that is repeated indefinitely.
   final ActionInterval action;
   double _elapsedInAction = 0.0;
 
@@ -325,6 +338,8 @@ abstract class ActionInstant extends Action {
     _finished = true;
   }
 
+  /// Called when the action is executed. If you are implementing your own
+  /// ActionInstant, override this method.
   void fire();
 }
 
@@ -546,6 +561,8 @@ class ActionController {
     }
   }
 
+  /// Steps the action forward by the specified time, typically there is no need
+  /// to directly call this method.
   void step(double dt) {
     for (int i = _actions.length - 1; i >= 0; i--) {
       Action action = _actions[i];

packages/flutter_sprites/lib/src/action_spline.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 Point _cardinalSplineAt(Point p0, Point p1, Point p2, Point p3, double tension, double t) {
@@ -17,6 +21,7 @@ Point _cardinalSplineAt(Point p0, Point p1, Point p2, Point p3, double tension,
   return new Point(x, y);
 }
 
+/// Signature for callbacks used by the [ActionSpline] to set a [Point] value.
 typedef void PointSetterCallback(Point value);
 
 /// The spline action is used to animate a point along a spline definied by

packages/flutter_sprites/lib/src/color_sequence.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A sequence of colors representing a gradient or a color transition over

packages/flutter_sprites/lib/src/constraint.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A constraint limits or otherwise controls a [Node]'s properties, such as
@@ -139,8 +143,13 @@ class ConstraintPositionToNode extends Constraint {
   /// same parent, but they need to be added to the same [SpriteBox].
   ConstraintPositionToNode(this.targetNode, {this.dampening, this.offset: Offset.zero});
 
+  /// Target node to follow.
   final Node targetNode;
+
+  /// Offset to the target node.
   final Offset offset;
+
+  /// Dampening used when following the [targetNode], value between 0.0 and 1.0.
   final double dampening;
 
   @override

packages/flutter_sprites/lib/src/effect_line.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
+/// Used by [EffectLine] to determine how the width of the line is calculated.
 enum EffectLineWidthMode {
+
+  /// Linear interpolation between minWidth at the start and maxWidth at the
+  /// end of the line.
   linear,
+
+  /// Creates a barrel shaped line, with minWidth at the end points of the line
+  /// and maxWidth at the middle.
   barrel,
 }
 
+/// Used by [EffectLine] to determine how the texture of the line is animated.
 enum EffectLineAnimationMode {
+
+  /// The texture of the line isn't animated.
   none,
+
+  /// The texture of the line is scrolling.
   scroll,
+
+  /// The texture of the line is set to a random position at every frame. This
+  /// mode is useful for creating flashing or electricity styled effects.
   random,
 }
 
+/// The EffectLine class is using the [TexturedLine] class to draw animated
+/// lines. These can be used to draw things such as smoke trails, electricity
+/// effects, or other animated types of lines.
 class EffectLine extends Node {
 
+  /// Creates a new EffectLine with the specified parameters. Only the
+  /// [texture] parameter is required, all other parameters are optional.
   EffectLine({
     this.texture: null,
     this.transferMode: TransferMode.dstOver,
@@ -49,22 +73,41 @@ class EffectLine extends Node {
     _painter.textureLoopLength = textureLoopLength;
   }
 
+  /// The texture used to draw the line.
   final Texture texture;
 
+  /// The transfer mode used to draw the line, default is
+  /// [TransferMode.dstOver].
   final TransferMode transferMode;
 
+  /// Mode used to calculate the width of the line.
   final EffectLineWidthMode widthMode;
+
+  /// The width of the line at its thinnest point.
   final double minWidth;
+
+  /// The width of the line at its thickest point.
   final double maxWidth;
+
+  /// The speed at which the line is growing, defined in points per second.
   final double widthGrowthSpeed;
 
+  /// The mode used to animate the texture of the line.
   final EffectLineAnimationMode animationMode;
+
+  /// The speed of which the texture of the line is scrolling. This property
+  /// is only used if the [animationMode] is set to
+  /// [EffectLineAnimationMode.scroll].
   final double scrollSpeed;
-  ColorSequence _colorSequence;
+
+  /// Color gradient used to draw the line, from start to finish.
   ColorSequence get colorSequence => _colorSequence;
 
-  List<Point> _points;
+  ColorSequence _colorSequence;
 
+  /// List of points that make up the line. Typically, you will only want to
+  /// set this at the beginning. Then use [addPoint] to add additional points
+  /// to the line.
   List<Point> get points => _points;
 
   set points(List<Point> points) {
@@ -75,15 +118,26 @@ class EffectLine extends Node {
     }
   }
 
+  List<Point> _points;
+
   List<double> _pointAges;
   List<Color> _colors;
   List<double> _widths;
 
+  /// The time it takes for an added point to fade out. It's total life time is
+  /// [fadeDuration] + [fadeAfterDelay].
   final double fadeDuration;
+
+  /// The time it takes until an added point starts to fade out.
   final double fadeAfterDelay;
 
+  /// The length, in points, that the texture is stretched to. If the
+  /// textureLoopLength is shorter than the line, the texture will be looped.
   final double textureLoopLength;
 
+  /// True if the line should be simplified by removing points that are close
+  /// to other points. This makes drawing faster, but can result in a slight
+  /// jittering effect when points are added.
   final bool simplify;
 
   TexturedLinePainter _painter;
@@ -168,6 +222,7 @@ class EffectLine extends Node {
     _painter.paint(canvas);
   }
 
+  /// Adds a new point to the end of the line.
   void addPoint(Point point) {
     // Skip duplicate points
     if (points.length > 0 && point.x == points[points.length - 1].x && point.y == points[points.length - 1].y)

packages/flutter_sprites/lib/src/image_map.dart

@@ -4,12 +4,18 @@
 
 part of flutter_sprites;
 
+/// The ImageMap is a helper class for loading and keeping references to
+/// multiple images.
 class ImageMap {
+
+  /// Creates a new ImageMap where images will be loaded from the specified
+  /// [bundle].
   ImageMap(AssetBundle bundle) : _bundle = bundle;
 
   final AssetBundle _bundle;
   final Map<String, ui.Image> _images = new Map<String, ui.Image>();
 
+  /// Loads a list of images given their urls.
   Future<List<ui.Image>> load(List<String> urls) {
     return Future.wait(urls.map(_loadImage));
   }
@@ -20,6 +26,9 @@ class ImageMap {
     return image;
   }
 
+  /// Returns a preloaded image, given its [url].
   ui.Image getImage(String url) => _images[url];
+
+  /// Returns a preloaded image, given its [url].
   ui.Image operator [](String url) => _images[url];
 }

packages/flutter_sprites/lib/src/label.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// Labels are used to display a string of text in a the node tree. To align

packages/flutter_sprites/lib/src/layer.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A [Node] that provides an intermediate rendering surface in the sprite

packages/flutter_sprites/lib/src/nine_slice_sprite.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A NineSliceSprite is similar to a [Sprite], but it it can strech its

packages/flutter_sprites/lib/src/node.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
+/// Converts degrees to radians.
 double convertDegrees2Radians(double degrees) => degrees * math.PI/180.8;
 
+/// Converts radians to degrees.
 double convertRadians2Degrees(double radians) => radians * 180.0/math.PI;
 
 /// A base class for all objects that can be added to the sprite node tree and rendered to screen using [SpriteBox] and
@@ -428,7 +434,8 @@ class Node {
     return _transformMatrixBoxToNode;
   }
 
-  Matrix4 inverseTransformMatrix() {
+  /// The inverse transform matrix used by this node.
+  Matrix4 get inverseTransformMatrix {
     if (_transformMatrixInverse == null) {
       _transformMatrixInverse = new Matrix4.copy(transformMatrix);
       _transformMatrixInverse.invert();

packages/flutter_sprites/lib/src/node3d.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// An node that transforms its children using a 3D perspective projection. This

packages/flutter_sprites/lib/src/node_with_size.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// The super class of any [Node] that has a size.

packages/flutter_sprites/lib/src/particle_system.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 class _Particle {
@@ -41,6 +45,8 @@ class _ParticleAccelerations {
 /// number of particles can never exceed the [maxParticles] limit.
 class ParticleSystem extends Node {
 
+  /// Creates a new particle system with the given properties. The only
+  /// required parameter is the texture, all other parameters are optional.
   ParticleSystem(this.texture,
                  {this.life: 1.5,
                   this.lifeVar: 1.0,
@@ -208,6 +214,8 @@ class ParticleSystem extends Node {
   double _emitCounter;
   int _numEmittedParticles = 0;
 
+  /// The over all opacity of the particle system. This value is multiplied by
+  /// the opacity of the individual particles.
   double opacity = 1.0;
 
   static Paint _paint = new Paint()

packages/flutter_sprites/lib/src/sound.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// An audio asset loaded by the SoundEffectPlayer.
 class SoundEffect {
+
+  /// Creates a new sound effect with the given sound id. Normally,
+  /// SoundEffect objects are created through the [SoundEffectPlayer].
   SoundEffect(this._soundId);
 
   int _soundId;
@@ -9,6 +16,9 @@ class SoundEffect {
 
 /// A sound being played by the SoundEffectPlayer.
 class SoundEffectStream {
+
+  /// Creates a new SoundEffectStream. Typically SoundEffectStream objects are
+  /// created by the SoundEffectPlayer.
   SoundEffectStream(SoundEffectPlayer player, int streamId, {
     double leftVolume,
     double rightVolume,
@@ -27,10 +37,12 @@ class SoundEffectStream {
 
   SoundPoolProxy get _soundPool => _player._soundPool;
 
+  /// Stop the sound effect.
   void stop() {
     _soundPool.ptr.stop(_streamId);
   }
 
+  /// True if the sound effect is paused.
   bool get paused => _paused;
   bool _paused;
   set paused(bool value) {
@@ -42,6 +54,7 @@ class SoundEffectStream {
     }
   }
 
+  /// Left volume of the sound effect, valid values are 0.0 to 1.0.
   double get leftVolume => _leftVolume;
   double _leftVolume;
   set leftVolume(double value) {
@@ -49,6 +62,7 @@ class SoundEffectStream {
     _soundPool.ptr.setVolume(_streamId, <double>[_leftVolume, _rightVolume]);
   }
 
+  /// Right volume of the sound effect, valid values are 0.0 to 1.0.
   double get rightVolume => _rightVolume;
   double _rightVolume;
   set rightVolume(double value) {
@@ -56,6 +70,8 @@ class SoundEffectStream {
     _soundPool.ptr.setVolume(_streamId, <double>[_leftVolume, _rightVolume]);
   }
 
+  /// The pitch of the sound effect, a value of 1.0 plays back the sound effect
+  /// at normal speed. Cannot be negative.
   double get pitch => _pitch;
   double _pitch;
   set pitch(double value) {
@@ -64,7 +80,11 @@ class SoundEffectStream {
   }
 }
 
+/// The SoundEffectPlayer loads and plays sound effects.
 class SoundEffectPlayer {
+
+  /// Creates a new SoundEffectPlayer with a max number of simultaneous
+  /// streams specified.
   SoundEffectPlayer(int maxStreams) {
     MediaServiceProxy mediaService = new MediaServiceProxy.unbound();
     shell.connectToService("mojo:media_service", mediaService);
@@ -76,6 +96,7 @@ class SoundEffectPlayer {
   bool _paused;
   int _nextStreamId = 0;
 
+  /// Loads a sound effect.
   Future<SoundEffect> load(MojoDataPipeConsumer data) async {
     SoundPoolLoadResponseParams result = await _soundPool.ptr.load(data);
     if (result.success)
@@ -84,6 +105,7 @@ class SoundEffectPlayer {
     throw new Exception('Unable to load sound');
   }
 
+  /// Plays a sound effect.
   Future<SoundEffectStream> play(SoundEffect sound, {
     double leftVolume: 1.0,
     double rightVolume: 1.0,
@@ -106,6 +128,7 @@ class SoundEffectPlayer {
     throw new Exception('Unable to play sound');
   }
 
+  /// Set to true to pause a sound effect.
   bool get paused => _paused;
 
   set paused(bool value) {
@@ -118,23 +141,44 @@ class SoundEffectPlayer {
   }
 }
 
+/// Signature for callbacks used by [SoundTrack].
 typedef void SoundTrackCallback(SoundTrack soundTrack);
+
+/// Signature for callbacks used by [SoundTrack].
 typedef void SoundTrackBufferingCallback(SoundTrack soundTrack, int index);
 
+/// A sound track is typically longer than a [SoundEffect]. Use sound tracks to
+/// play back music or ambient sounds.
 class SoundTrack {
   MediaPlayerProxy _player;
 
+  /// Called when the sound has finished playing.
   SoundTrackCallback onSoundComplete;
+
+  /// Called when a seek operation has finished.
   SoundTrackCallback onSeekComplete;
+
+  /// Called when buffering is being performed.
   SoundTrackBufferingCallback onBufferingUpdate;
+
+  /// If true, the sound track will automatically loop.
   bool loop;
+
+  /// The current playback time in seconds.
   double time;
+
+  /// The volume the sound track is currently played at, valid range is 0.0 to
+  /// 1.0.
   double volume;
 }
 
 SoundTrackPlayer _sharedSoundTrackPlayer;
 
+/// Loads and plays [SoundTrack]s.
 class SoundTrackPlayer {
+
+  /// Creates a new [SoundTrackPlayer], typically you will want to use the
+  /// [sharedInstance] method to receive the player.
   SoundTrackPlayer() {
     _mediaService = new MediaServiceProxy.unbound();
     shell.connectToService("mojo:media_service", _mediaService);
@@ -144,10 +188,13 @@ class SoundTrackPlayer {
 
   Set<SoundTrack> _soundTracks = new HashSet<SoundTrack>();
 
+  /// Retrives a singleton object of the SoundTrackPlayer, use this method
+  /// in favor for the constructor.
   static SoundTrackPlayer sharedInstance() {
     return _sharedSoundTrackPlayer ??= new SoundTrackPlayer();
   }
 
+  /// Loads a [SoundTrack].
   Future<SoundTrack> load(Future<MojoDataPipeConsumer> pipe) async {
     // Create media player
     SoundTrack soundTrack = new SoundTrack();
@@ -158,11 +205,13 @@ class SoundTrackPlayer {
     return soundTrack;
   }
 
+  /// Unloads a [SoundTrack] from memory.
   void unload(SoundTrack soundTrack) {
     stop(soundTrack);
     _soundTracks.remove(soundTrack);
   }
 
+  /// Plays a [SoundTrack].
   void play(SoundTrack soundTrack, {
     bool loop: false,
     double volume: 1.0,
@@ -175,15 +224,19 @@ class SoundTrackPlayer {
     _soundTracks.add(soundTrack);
   }
 
+  /// Stops a [SoundTrack]. You may also want to call the [unload] method to
+  /// remove if from memory if you are not planning to play it again.
   void stop(SoundTrack track) {
     track._player.ptr.pause();
   }
 
+  /// Pauses all [SoundTrack]s that are currently playing.
   void pauseAll() {
     for (SoundTrack soundTrack in _soundTracks)
       soundTrack._player.ptr.pause();
   }
 
+  /// Resumes all [SoundTrack]s that have been loaded by this player.
   void resumeAll() {
     for (SoundTrack soundTrack in _soundTracks)
       soundTrack._player.ptr.start();

packages/flutter_sprites/lib/src/sprite.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A Sprite is a [Node] that renders a bitmap image to the screen.
@@ -84,6 +88,8 @@ class Sprite extends NodeWithSize with SpritePaint {
   }
 }
 
+/// Defines properties, such as [opacity] and [transferMode] that are shared
+/// between [Node]s that render textures to screen.
 abstract class SpritePaint {
   double _opacity = 1.0;
 

packages/flutter_sprites/lib/src/sprite_box.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
-/// Options for setting up a [SpriteBox].
-///
-///  * [nativePoints]: use the same points as the parent [Widget].
-///  * [letterbox]: use the size of the root node for the coordinate system, and constrain the aspect ratio and trim off
-///    areas that end up outside the screen.
-///  * [stretch]: use the size of the root node for the coordinate system, and scale it to fit the size of the box.
-///  * [scaleToFit]: similar to the letterbox option, but instead of trimming areas the sprite system will be scaled
-///    down to fit the box.
-///  * [fixedWidth]: use the width of the root node to set the size of the coordinate system, and change
-///    the height of the root node to fit the box.
-///  * [fixedHeight]: use the height of the root node to set the size of the coordinate system, and change
-///    the width of the root node to fit the box.
+/// Options for setting up a [SpriteBox]'s coordinate system.
 enum SpriteBoxTransformMode {
+  /// Use the same points as the parent [Widget].
   nativePoints,
+
+  /// Use the size of the root node for the coordinate system, and constrain the
+  /// aspect ratio and trim off areas that end up outside the screen.
   letterbox,
+
+  /// Use the size of the root node for the coordinate system, and scale it to
+  /// fit the size of the box.
   stretch,
+
+  /// Similar to the letterbox option, but instead of trimming areas the sprite
+  /// system will be scaled down to fit the box.
   scaleToFit,
+
+  /// Use the width of the root node to set the size of the coordinate system,
+  /// and change the height of the root node to fit the box.
   fixedWidth,
+
+  /// Use the height of the root node to set the size of the coordinate system,
+  /// and change the width of the root node to fit the box.
   fixedHeight,
 }
 
+/// A [RenderBox] that draws a sprite world represented by a [Node] tree.
 class SpriteBox extends RenderBox {
 
   // Setup
@@ -71,31 +81,6 @@ class SpriteBox extends RenderBox {
 
   // Member variables
 
-  // Root node for drawing
-  NodeWithSize _rootNode;
-
-  set rootNode (NodeWithSize value) {
-    if (value == _rootNode) return;
-
-    // Ensure that the root node has a size
-    assert(_transformMode == SpriteBoxTransformMode.nativePoints
-      || value.size.width > 0);
-    assert(_transformMode == SpriteBoxTransformMode.nativePoints
-      || value.size.height > 0);
-
-    // Remove sprite box references
-    if (_rootNode != null)
-      _removeSpriteBoxReference(_rootNode);
-
-    // Update the value
-    _rootNode = value;
-    _actionControllers = null;
-
-    // Add new references
-    _addSpriteBoxReference(_rootNode);
-    markNeedsLayout();
-  }
-
   // Tracking of frame rate and updates
   Duration _lastTimeStamp;
   double _frameRate = 0.0;
@@ -126,14 +111,16 @@ class SpriteBox extends RenderBox {
 
   List<Node> _constrainedNodes;
 
-  Rect _visibleArea;
-
+  /// A rectangle that represents the visible area of the sprite world's
+  /// coordinate system.
   Rect get visibleArea {
     if (_visibleArea == null)
       _calcTransformMatrix();
     return _visibleArea;
   }
 
+  Rect _visibleArea;
+
   bool _initialized = false;
 
   // Properties
@@ -143,6 +130,30 @@ class SpriteBox extends RenderBox {
   ///     var rootNode = mySpriteBox.rootNode;
   NodeWithSize get rootNode => _rootNode;
 
+  NodeWithSize _rootNode;
+
+  set rootNode (NodeWithSize value) {
+    if (value == _rootNode) return;
+
+    // Ensure that the root node has a size
+    assert(_transformMode == SpriteBoxTransformMode.nativePoints
+      || value.size.width > 0);
+    assert(_transformMode == SpriteBoxTransformMode.nativePoints
+      || value.size.height > 0);
+
+    // Remove sprite box references
+    if (_rootNode != null)
+      _removeSpriteBoxReference(_rootNode);
+
+    // Update the value
+    _rootNode = value;
+    _actionControllers = null;
+
+    // Add new references
+    _addSpriteBoxReference(_rootNode);
+    markNeedsLayout();
+  }
+
   @override
   void performLayout() {
     size = constraints.biggest;

packages/flutter_sprites/lib/src/sprite_widget.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A widget that uses a [SpriteBox] to render a sprite node tree to the screen.

packages/flutter_sprites/lib/src/spritesheet.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A sprite sheet packs a number of smaller images into a single large image.

packages/flutter_sprites/lib/src/texture.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 /// A texture represents a rectangular area of an image and is typically used to draw a sprite to the screen.
@@ -65,6 +69,7 @@ class Texture {
   ///     myTexture.pivot = new Point(0.5, 0.5);
   Point pivot;
 
+  /// Creates a new Texture from a part of the current texture.
   Texture textureFromRect(Rect rect, [String name = null]) {
     assert(rect != null);
     assert(!rotated);
@@ -73,6 +78,8 @@ class Texture {
     return new Texture._fromSpriteFrame(image, name, rect.size, false, false, srcFrame, dstFrame, new Point(0.5, 0.5));
   }
 
+  /// Draws the texture to a [Canvas] at a specified [position] and with the
+  /// specified [paint].
   void drawTexture(Canvas canvas, Point position, Paint paint) {
     // Get drawing position
     double x = position.x;

packages/flutter_sprites/lib/src/textured_line.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
+/// A [Node] that draws a polyline from a list of points using the provided
+/// [Texture]. The textured line draws static lines. If you want to create an
+/// animated line, consider using the [EffectLine] instead.
 class TexturedLine extends Node {
+
+  /// Creates a new TexturedLine.
   TexturedLine(List<Point> points, List<Color> colors, List<double> widths, [Texture texture, List<double> textureStops]) {
     painter = new TexturedLinePainter(points, colors, widths, texture, textureStops);
   }
 
+  /// The painter used to draw the line.
   TexturedLinePainter painter;
 
   @override
@@ -13,26 +23,34 @@ class TexturedLine extends Node {
   }
 }
 
+/// Draws a polyline to a [Canvas] from a list of points using the provided [Texture].
 class TexturedLinePainter {
   TexturedLinePainter(this._points, this.colors, this.widths, [Texture texture, this.textureStops]) {
     this.texture = texture;
   }
 
-  List<Point> _points;
-
+  /// The points that makes up the polyline.
   List<Point> get points => _points;
 
+  List<Point> _points;
+
   set points(List<Point> points) {
     _points = points;
     _calculatedTextureStops = null;
   }
 
+  /// The color of each point on the polyline. The color of the line will be
+  /// interpolated between the points.
   List<Color> colors;
+
+  /// The width of the line at each point on the polyline.
   List<double> widths;
-  Texture _texture;
 
+  /// The texture this line will be drawn using.
   Texture get texture => _texture;
 
+  Texture _texture;
+
   set texture(Texture texture) {
     _texture = texture;
     if (texture == null) {
@@ -47,41 +65,51 @@ class TexturedLinePainter {
     }
   }
 
+  /// Defines the position in the texture for each point on the polyline.
   List<double> textureStops;
 
-  List<double> _calculatedTextureStops;
-
+  /// The [textureStops] used if no explicit texture stops has been provided.
   List<double> get calculatedTextureStops {
     if (_calculatedTextureStops == null)
       _calculateTextureStops();
     return _calculatedTextureStops;
   }
 
+  List<double> _calculatedTextureStops;
+
   double _length;
 
+  /// The length of the line.
   double get length {
     if (_calculatedTextureStops == null)
       _calculateTextureStops();
     return _length;
   }
 
+  /// The offset of the texture on the line.
   double textureStopOffset = 0.0;
 
-  double _textureLoopLength;
-
+  /// The length, in points, that the texture is stretched to. If the
+  /// textureLoopLength is shorter than the line, the texture will be looped.
   double get textureLoopLength => textureLoopLength;
 
+  double _textureLoopLength;
+
   set textureLoopLength(double textureLoopLength) {
     _textureLoopLength = textureLoopLength;
     _calculatedTextureStops = null;
   }
 
+  /// If true, the textured line attempts to remove artifacts at sharp corners
+  /// on the polyline.
   bool removeArtifacts = true;
 
+  /// The [TransferMode] used to draw the line to the [Canvas].
   TransferMode transferMode = TransferMode.srcOver;
 
   Paint _cachedPaint = new Paint();
 
+  /// Paints the line to the [canvas].
   void paint(Canvas canvas) {
     // Check input values
     assert(_points != null);

packages/flutter_sprites/lib/src/util.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
 

packages/flutter_sprites/lib/src/virtual_joystick.dart

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 part of flutter_sprites;
 
+/// Provides a virtual joystick that can easily be added to your sprite scene.
 class VirtualJoystick extends NodeWithSize {
+
+  /// Creates a new virtual joystick.
   VirtualJoystick() : super(new Size(160.0, 160.0)) {
     userInteractionEnabled = true;
     handleMultiplePointers = false;
@@ -17,11 +24,15 @@ class VirtualJoystick extends NodeWithSize {
       ..style = PaintingStyle.stroke;
   }
 
-  Point _value = Point.origin;
+  /// Reads the current value of the joystick. A point with from (-1.0, -1.0)
+  /// to (1.0, 1.0). If the joystick isn't moved it will return (0.0, 0.0).
   Point get value => _value;
+  Point _value = Point.origin;
 
-  bool _isDown = false;
+  /// True if the user is currently touching the joystick.
   bool get isDown => _isDown;
+  bool _isDown = false;
+
 
   Point _pointerDownAt;
   Point _center;