Fix ImageShader crash, and add dartdocs

Adds or augments the documentation of various objects in dart:ui.

Removes the ignored argument to SceneBuilder.

Hide the default constructor on Gradient.

Add a call to the ImageShader constructor.

Reorder some members so that private versions come after public versions
so that docs will come before both.

sky/engine/core/dart/compositing.dart

@@ -5,7 +5,18 @@
 part of dart_ui;
 
 /// An opaque object representing a composited scene.
-abstract class Scene extends NativeFieldWrapperClass2 {
+///
+/// To create a Scene object, use a [SceneBuilder].
+///
+/// Scene objects can be displayed on the screen using the
+/// [Window.render] method.
+class Scene extends NativeFieldWrapperClass2 {
+  /// Creates an uninitialized Scene object.
+  ///
+  /// Calling the Scene constructor directly will not create a useable
+  /// object. To create a Scene object, use a [SceneBuilder].
+  Scene(); // (this constructor is here just so we can document it)
+
   /// Releases the resources used by this scene.
   ///
   /// After calling this function, the scene is cannot be used further.
@@ -13,9 +24,15 @@ abstract class Scene extends NativeFieldWrapperClass2 {
 }
 
 /// Builds a [Scene] containing the given visuals.
+///
+/// A [Scene] can then be rendered using [Window.render].
+///
+/// To draw graphical operations onto a [Scene], first create a
+/// [Picture] using a [PictureRecorder] and a [Canvas], and then add
+/// it to the scene using [addPicture].
 class SceneBuilder extends NativeFieldWrapperClass2 {
-  // TODO(abarth): Remove this ignored "bounds" argument.
-  SceneBuilder([Rect bounds]) { _constructor(); }
+  /// Creates an empty [SceneBuilder] object.
+  SceneBuilder() { _constructor(); }
   void _constructor() native "SceneBuilder_constructor";
 
   /// Pushes a transform operation onto the operation stack.
@@ -87,7 +104,7 @@ class SceneBuilder extends NativeFieldWrapperClass2 {
   /// controls where the statistics are displayed.
   void addPerformanceOverlay(int enabledOptions, Rect bounds) native "SceneBuilder_addPerformanceOverlay";
 
-  /// Adds a picture to the scene.
+  /// Adds a [Picture] to the scene.
   ///
   /// The picture is rasterized at the given offset.
   void addPicture(Offset offset, Picture picture) native "SceneBuilder_addPicture";
@@ -113,8 +130,9 @@ class SceneBuilder extends NativeFieldWrapperClass2 {
 
   /// Finishes building the scene.
   ///
-  /// Returns a [Scene] containing the objects that have been added to this
-  /// scene builder.
+  /// Returns a [Scene] containing the objects that have been added to
+  /// this scene builder. The [Scene] can then be displayed on the
+  /// screen with [Window.render].
   ///
   /// After calling this function, the scene builder object is invalid and
   /// cannot be used further.

sky/engine/core/dart/painting.dart

@@ -44,9 +44,14 @@ void decodeImageFromList(Uint8List list, ImageDecoderCallback callback)
 /// whether a line from a given point on the plane to a point at infinity
 /// intersects the path an even (non-enclosed) or an odd (enclosed) number of
 /// times.
+///
+/// Paths can be drawn on canvases using [Canvas.drapPath], and can
+/// used to create clip regions using [Canvas.clipPath].
 class Path extends NativeFieldWrapperClass2 {
-  void _constructor() native "Path_constructor";
+
+  /// Create a new empty [Path] object.
   Path() { _constructor(); }
+  void _constructor() native "Path_constructor";
 
   void moveTo(double x, double y) native "Path_moveTo";
   void relativeMoveTo(double dx, double dy) native "Path_relativeMoveTo";
@@ -94,22 +99,21 @@ int _makeBlurFlags(bool ignoreTransform, bool highQuality) {
 }
 
 class MaskFilter extends NativeFieldWrapperClass2 {
-  void _constructor(int style, double sigma, int flags) native "MaskFilter_constructor";
   MaskFilter.blur(BlurStyle style, double sigma,
                   {bool ignoreTransform: false, bool highQuality: false}) {
     _constructor(style.index, sigma, _makeBlurFlags(ignoreTransform, highQuality));
   }
+  void _constructor(int style, double sigma, int flags) native "MaskFilter_constructor";
 }
 
 class ColorFilter extends NativeFieldWrapperClass2 {
-  void _constructor(Color color, TransferMode transferMode) native "ColorFilter_constructor";
   ColorFilter.mode(Color color, TransferMode transferMode) {
     _constructor(color, transferMode);
   }
+  void _constructor(Color color, TransferMode transferMode) native "ColorFilter_constructor";
 }
 
-abstract class Shader extends NativeFieldWrapperClass2 {
-}
+abstract class Shader extends NativeFieldWrapperClass2 { }
 
 /// Defines what happens at the edge of the gradient.
 enum TileMode {
@@ -128,9 +132,12 @@ void _validateColorStops(List<Color> colors, List<double> colorStops) {
 }
 
 class Gradient extends Shader {
+  /// Creates a Gradient object that is not initialized.
+  ///
+  /// Use the [Gradient.linear] or [Gradient.radial] constructors to
+  /// obtain a usable [Gradient] object.
+  Gradient();
   void _constructor() native "Gradient_constructor";
-  void _initLinear(List<Point> endPoints, List<Color> colors, List<double> colorStops, int tileMode) native "Gradient_initLinear";
-  void _initRadial(Point center, double radius, List<Color> colors, List<double> colorStops, int tileMode) native "Gradient_initRadial";
 
   /// Creates a linear gradient from [endPoint[0]] to [endPoint[1]]. If
   /// [colorStops] is provided, [colorStops[i]] is a number from 0 to 1 that
@@ -146,6 +153,7 @@ class Gradient extends Shader {
     _validateColorStops(colors, colorStops);
     _initLinear(endPoints, colors, colorStops, tileMode.index);
   }
+  void _initLinear(List<Point> endPoints, List<Color> colors, List<double> colorStops, int tileMode) native "Gradient_initLinear";
 
   /// Creates a radial gradient centered at [center] that ends at [radius]
   /// distance from the center. If [colorStops] is provided, [colorStops[i]] is
@@ -160,12 +168,10 @@ class Gradient extends Shader {
     _validateColorStops(colors, colorStops);
     _initRadial(center, radius, colors, colorStops, tileMode.index);
   }
+  void _initRadial(Point center, double radius, List<Color> colors, List<double> colorStops, int tileMode) native "Gradient_initRadial";
 }
 
 class ImageShader extends Shader {
-  void _constructor() native "ImageShader_constructor";
-  void _initWithImage(Image image, int tmx, int tmy, Float64List matrix4) native "ImageShader_initWithImage";
-
   ImageShader(Image image, TileMode tmx, TileMode tmy, Float64List matrix4) {
     if (image == null)
       throw new ArgumentError("[image] argument cannot be null");
@@ -175,8 +181,11 @@ class ImageShader extends Shader {
       throw new ArgumentError("[tmy] argument cannot be null");
     if (matrix4 == null)
       throw new ArgumentError("[matrix4] argument cannot be null");
+    _constructor();
     _initWithImage(image, tmx.index, tmy.index, matrix4);
   }
+  void _constructor() native "ImageShader_constructor";
+  void _initWithImage(Image image, int tmx, int tmy, Float64List matrix4) native "ImageShader_initWithImage";
 }
 
 /// Defines how a list of points is interpreted when drawing a set of triangles.
@@ -189,37 +198,64 @@ enum VertexMode {
 
 /// An interface for recording graphical operations.
 ///
-/// To record graphical operations, first create a [PictureRecorder], then
-/// construct a Canvas using the picture recorder. After issuing all the
-/// graphical operations, call the [endRecording] function on the picture
-/// recorder to obtain the final [Picture]. The [Picture] can then be included
-/// in a composited [Scene] via a [SceneBuilder]. Finally, the [Scene] can be
-/// displayed to the user via the [render] function on [Window].
+/// [Canvas] objects are used in creating [Picture] objects, which can
+/// themselves be used with a [SceneBuilder] to build a [Scene]. In
+/// normal usage, however, this is all handled by the framework.
 class Canvas extends NativeFieldWrapperClass2 {
-  void _constructor(PictureRecorder recorder, Rect cullRect) native "Canvas_constructor";
-
-  /// Constructs a canvas for recording graphical operations into the given picture recorder.
+  /// Creates a canvas for recording graphical operations into the
+  /// given picture recorder.
   ///
   /// Graphical operations that affect pixels entirely outside the given
   /// cullRect might be discarded by the implementation. However, the
   /// implementation might draw outside these bounds if, for example, a command
   /// draws partially inside and outside the cullRect. To ensure that pixels
   /// outside a given region are discarded, consider using a [clipRect].
+  ///
+  /// To end the recording, call [PictureRecorder.endRecording] on the
+  /// given recorder.
   Canvas(PictureRecorder recorder, Rect cullRect) {
     if (recorder == null)
-      throw new ArgumentError("[recorder] argument cannot be null.");
+      throw new ArgumentError('[recorder] argument cannot be null.');
     if (recorder.isRecording)
-      throw new ArgumentError("You must call endRecording() before reusing a PictureRecorder to create a new Canvas object.");
+      throw new ArgumentError('You must call endRecording() before reusing a PictureRecorder to create a new Canvas object.');
     _constructor(recorder, cullRect);
   }
+  void _constructor(PictureRecorder recorder, Rect cullRect) native "Canvas_constructor";
 
+  /// Saves a copy of the current transform and clip on the save stack.
+  ///
+  /// Call [restore] to pop the save stack.
   void save() native "Canvas_save";
-  // TODO(jackson): Paint should be optional, but making it optional causes crash
-  void saveLayer(Rect bounds, Paint paint) native "Canvas_saveLayer";
+ 
+  /// Saves a copy of the current transform and clip on the save
+  /// stack, and then creates a new group which subsequent calls will
+  /// become a part of. When the save stack is later popped, the group
+  /// will be flattened and have the given paint applied.
+  ///
+  /// This lets you create composite effects, for example making a
+  /// group of drawing commands semi-transparent. Without using
+  /// [saveLayer], each part of the group would be painted
+  /// individually, so where they overlap would be darker than where
+  /// they do not. By using [saveLayer] to group them together, they
+  /// can be drawn with an opaque color at first, and then the entire
+  /// group can be made transparent using the [saveLayer]'s paint.
+  ///
+  /// Call [restore] to pop the save stack and apply the paint to the
+  /// group.
+  void saveLayer(Rect bounds, Paint paint) native "Canvas_saveLayer"; // TODO(jackson): Paint should be optional, but making it optional causes crash
+
+  /// Pops the current save stack, if there is anything to pop.
+  /// Otherwise, does nothing.
+  ///
+  /// Use [save] and [saveLayer] to push state onto the stack.
   void restore() native "Canvas_restore";
   
-  /// Returns 1 for a clean canvas; each call to save() or saveLayer()
-  /// increments it, and each call to restore() decrements it.
+  /// Returns the number of items on the save stack, including the
+  /// initial state. This means it returns 1 for a clean canvas, and
+  /// that each call to [save] and [saveLayer] increments it, and that
+  /// each matching call to [restore] decrements it.
+  ///
+  /// This number cannot go below 1.
   int getSaveCount() native "Canvas_getSaveCount";
   
   void translate(double dx, double dy) native "Canvas_translate";
@@ -227,19 +263,19 @@ class Canvas extends NativeFieldWrapperClass2 {
   void rotate(double radians) native "Canvas_rotate";
   void skew(double sx, double sy) native "Canvas_skew";
 
-  void _transform(Float64List matrix4) native "Canvas_transform";
   void transform(Float64List matrix4) {
     if (matrix4.length != 16)
       throw new ArgumentError("[matrix4] must have 16 entries.");
     _transform(matrix4);
   }
+  void _transform(Float64List matrix4) native "Canvas_transform";
 
-  void _setMatrix(Float64List matrix4) native "Canvas_setMatrix";
   void setMatrix(Float64List matrix4) {
     if (matrix4.length != 16)
       throw new ArgumentError("[matrix4] must have 16 entries.");
     _setMatrix(matrix4);
   }
+  void _setMatrix(Float64List matrix4) native "Canvas_setMatrix";
 
   Float64List getTotalMatrix() native "Canvas_getTotalMatrix";
   void clipRect(Rect rect) native "Canvas_clipRect";
@@ -263,15 +299,10 @@ class Canvas extends NativeFieldWrapperClass2 {
   void drawImageRect(Image image, Rect src, Rect dst, Paint paint) native "Canvas_drawImageRect";
 
   void drawImageNine(Image image, Rect center, Rect dst, Paint paint) native "Canvas_drawImageNine";
-  void drawPicture(Picture picture) native "Canvas_drawPicture";
 
-  void _drawVertices(int vertexMode,
-                     List<Point> vertices,
-                     List<Point> textureCoordinates,
-                     List<Color> colors,
-                     TransferMode transferMode,
-                     List<int> indicies,
-                     Paint paint) native "Canvas_drawVertices";
+  /// Draw the given picture onto the canvas. To create a picture, see
+  /// [PictureRecorder].
+  void drawPicture(Picture picture) native "Canvas_drawPicture";
 
   void drawVertices(VertexMode vertexMode,
                     List<Point> vertices,
@@ -295,15 +326,13 @@ class Canvas extends NativeFieldWrapperClass2 {
     }
     _drawVertices(vertexMode.index, vertices, textureCoordinates, colors, transferMode, indicies, paint);
   }
-
-  // TODO(eseidel): Paint should be optional, but optional doesn't work.
-  void _drawAtlas(Image image,
-                  List<RSTransform> transforms,
-                  List<Rect> rects,
-                  List<Color> colors,
-                  TransferMode mode,
-                  Rect cullRect,
-                  Paint paint) native "Canvas_drawAtlas";
+  void _drawVertices(int vertexMode,
+                     List<Point> vertices,
+                     List<Point> textureCoordinates,
+                     List<Color> colors,
+                     TransferMode transferMode,
+                     List<int> indicies,
+                     Paint paint) native "Canvas_drawVertices";
 
   void drawAtlas(Image image,
                  List<RSTransform> transforms,
@@ -326,6 +355,14 @@ class Canvas extends NativeFieldWrapperClass2 {
     }
     _drawAtlas(image, transforms, rects, colors, mode, cullRect, paint);
   }
+  void _drawAtlas(Image image,
+                  List<RSTransform> transforms,
+                  List<Rect> rects,
+                  List<Color> colors,
+                  TransferMode mode,
+                  Rect cullRect,
+                  // TODO(eseidel): Paint should be optional, but optional doesn't work.
+                  Paint paint) native "Canvas_drawAtlas";
 }
 
 /// An object representing a sequence of recorded graphical operations.

sky/engine/core/dart/text.dart

@@ -106,7 +106,7 @@ enum TextBaseline {
 class TextDecoration {
   const TextDecoration._(this._mask);
 
-  /// Constructs a decoration that paints the union of all the given decorations.
+  /// Creates a decoration that paints the union of all the given decorations.
   factory TextDecoration.combine(List<TextDecoration> decorations) {
     int mask = 0;
     for (TextDecoration decoration in decorations)
@@ -262,7 +262,7 @@ Int32List _encodeTextStyle(Color color,
 
 /// An opaque object that determines the size, position, and rendering of text.
 class TextStyle {
-  /// Constructs a new TextStyle object.
+  /// Creates a new TextStyle object.
   ///
   /// * [color] The color to use when painting the text.
   /// * [decoration] The decorations to paint near the text (e.g., an underline).
@@ -382,7 +382,7 @@ Int32List _encodeParagraphStyle(TextAlign textAlign,
 
 /// An opaque object that determines the position of lines within a paragraph of text.
 class ParagraphStyle {
-  /// Constructs a new ParagraphStyle object.
+  /// Creates a new ParagraphStyle object.
   ///
   /// * [textAlign] .
   /// * [textBaseline] .

sky/engine/core/dart/window.dart

@@ -44,6 +44,13 @@ class WindowPadding {
 /// consisting of a language and a country. This is a subset of locale
 /// identifiers as defined by BCP 47.
 class Locale {
+  /// Creates a new Locale object. The first argument is the
+  /// primary language subtag, the second is the region subtag.
+  ///
+  /// For example:
+  ///
+  ///     const Locale swissFrench = const Locale('fr', 'CH');
+  ///     const Locale canadianFrench = const Locale('fr', 'CA');
   const Locale(this.languageCode, this.countryCode);
 
   /// The primary language subtag for the locale.
@@ -73,6 +80,9 @@ class Locale {
 }
 
 /// The most basic interface to the host operating system's user interface.
+///
+/// There is a single Window instance in the system, which you can
+/// obtain from the [window] property.
 class Window {
   Window._();
 
@@ -141,6 +151,18 @@ class Window {
   /// Updates the application's rendering on the GPU with the newly provided
   /// [Scene]. For optimal performance, this should only be called in response
   /// to the [onBeginFrame] callback being invoked.
+  ///
+  /// To record graphical operations, first create a
+  /// [PictureRecorder], then construct a [Canvas], passing that
+  /// [PictureRecorder] to its constructor. After issuing all the
+  /// graphical operations, call the [endRecording] function on the
+  /// [PictureRecorder] to obtain the final [Picture] that represents
+  /// the issued graphical operations.
+  /// 
+  /// Next, create a [SceneBuilder], and add the [Picture] to it using
+  /// [SceneBuilder.addPicture]. With the [SceneBuilder.build] method
+  /// you can then obtain a [Scene] object, which you can display to
+  /// the user via this [render] function.
   void render(Scene scene) native "Window_render";
 
   /// Flushes pending real-time events, executing their callbacks.