Various documentation improvements

Author: Hixie

lib/ui/compositing.dart

@@ -367,6 +367,10 @@ abstract class SceneBuilder {
   /// The given color is applied to the objects' rasterization using the given
   /// blend mode.
   ///
+  /// This method is a strict subset of [pushImageFilter] (because [ColorFilter]
+  /// implements [ImageFilter]); it is always correct to use [pushImageFilter]
+  /// where one might have used [pushColorFilter].
+  ///
   /// {@macro dart.ui.sceneBuilder.oldLayer}
   ///
   /// {@macro dart.ui.sceneBuilder.oldLayerVsRetained}
@@ -379,8 +383,8 @@ abstract class SceneBuilder {
 
   /// Pushes an image filter operation onto the operation stack.
   ///
-  /// The given filter is applied to the children's rasterization before compositing them into
-  /// the scene.
+  /// The given filter is applied to the children's rasterization before
+  /// compositing them into the scene.
   ///
   /// {@macro dart.ui.sceneBuilder.oldLayer}
   ///

lib/ui/geometry.dart

@@ -4,6 +4,9 @@
 
 part of dart.ui;
 
+// Examples can assume:
+// RSTransfrom rst;
+
 /// Base class for [Size] and [Offset], which are both ways to describe
 /// a distance as a two-dimensional axis-aligned vector.
 abstract class OffsetBase {
@@ -1749,6 +1752,17 @@ class RRect {
 ///
 /// Used by [Canvas.drawAtlas]. This is a more efficient way to represent these
 /// simple transformations than a full matrix.
+///
+/// It is equivalent to a [Matrix4] built using the following parameters (where
+/// `rst` is the corresponding `RSTransform` instance):
+///
+/// ```dart
+/// // Matrix4's constructor arguments are in column-major order.
+/// Matrix4(rst.scos, rst.ssin, 0, 0,
+///        -rst.ssin, rst.scos, 0, 0,
+///         0, 0, 1, 0,
+///         rst.tx, rst.ty, 0, 1);
+/// ```
 // Modeled after Skia's SkRSXform.
 class RSTransform {
   /// Creates an RSTransform.

lib/ui/painting.dart

@@ -5366,12 +5366,26 @@ abstract class Canvas {
   void drawPath(Path path, Paint paint);
 
   /// Draws the given [Image] into the canvas with its top-left corner at the
-  /// given [Offset]. The image is composited into the canvas using the given [Paint].
+  /// given [Offset].
+  ///
+  /// The image is composited into the canvas using the given [Paint], by
+  /// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
+  /// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
+  /// properties of the `paint` argument (in that order).
+  ///
+  /// Multiple calls to this method with different arguments (from the same
+  /// image) can be batched into a single call to [drawAtlas] to improve
+  /// performance.
   void drawImage(Image image, Offset offset, Paint paint);
 
   /// Draws the subset of the given image described by the `src` argument into
   /// the canvas in the axis-aligned rectangle given by the `dst` argument.
   ///
+  /// The image is composited into the canvas using the given [Paint], by
+  /// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
+  /// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
+  /// properties of the `paint` argument (in that order).
+  ///
   /// This might sample from outside the `src` rect by up to half the width of
   /// an applied filter.
   ///
@@ -5380,7 +5394,7 @@ abstract class Canvas {
   /// performance.
   void drawImageRect(Image image, Rect src, Rect dst, Paint paint);
 
-  /// Draws the given [Image] into the canvas using the given [Paint].
+  /// Draws the given [Image] into the canvas as a nine-patch image.
   ///
   /// The image is drawn in nine portions described by splitting the image by
   /// drawing two horizontal lines and two vertical lines, where the `center`
@@ -5393,6 +5407,15 @@ abstract class Canvas {
   /// five regions are drawn by stretching them to fit such that they exactly
   /// cover the destination rectangle while maintaining their relative
   /// positions.
+  ///
+  /// The image is composited into the canvas using the given [Paint], by
+  /// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
+  /// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
+  /// properties of the `paint` argument (in that order).
+  ///
+  /// See also:
+  ///
+  ///  * <https://en.wikipedia.org/wiki/9-slice_scaling>
   void drawImageNine(Image image, Rect center, Rect dst, Paint paint);
 
   /// Draw the given picture onto the canvas. To create a picture, see
@@ -5499,15 +5522,18 @@ abstract class Canvas {
   /// [blendMode] argument (if a color is specified). In this part of the operation,
   /// the image part will be considered the source of the operation and the associated
   /// color will be considered the destination.
-  /// - Blend the result from the first step onto the canvas using the translation,
-  /// rotation, and scale properties expressed in the associated entry in the
-  /// [transforms] list using the properties of the [Paint] object.
-  ///
-  /// If the first stage of the operation which blends each part of the image with
-  /// a color is needed, then both the [colors] and [blendMode] arguments must
-  /// not be null and there must be an entry in the [colors] list for each
-  /// image part. If that stage is not needed, then the [colors] argument can
-  /// be either null or an empty list and the [blendMode] argument may also be null.
+  ///
+  /// - Blend the result from the first step onto the canvas using the
+  /// translation, rotation, and scale properties expressed in the associated
+  /// entry in the [transforms] list, and the [Paint.color] (alpha channel
+  /// only), [Paint.blendMode], [Paint.colorFilter], [Paint.maskFilter], and
+  /// [Paint.imageFilter] properties of the `paint` argument (in that order).
+  ///
+  /// If the first stage of the operation which blends each part of the image
+  /// with a color is needed, then both the [colors] and [blendMode] arguments
+  /// must not be null and there must be an entry in the [colors] list for each
+  /// image part. If the [colors] argument is null or empty, or if the
+  /// [blendMode] argument is null, then this stage is skipped.
   ///
   /// The optional [cullRect] argument can provide an estimate of the bounds of the
   /// coordinates rendered by all components of the atlas to be compared against