Add more documentation around layers. (#45648)

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

@@ -182,11 +182,12 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   @protected
   void handleTextScaleFactorChanged() { }
 
-  /// {@template on_platform_brightness_change}
   /// Called when the platform brightness changes.
   ///
-  /// The current platform brightness can be queried either from a Flutter
-  /// binding, or from a [MediaQuery] widget.
+  /// The current platform brightness can be queried from a Flutter binding or
+  /// from a [MediaQuery] widget. The latter is preferred from widgets because
+  /// it causes the widget to be automatically rebuilt when the brightness
+  /// changes.
   ///
   /// {@tool sample}
   /// Querying [Window.platformBrightness].
@@ -197,7 +198,7 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// {@end-tool}
   ///
   /// {@tool sample}
-  /// Querying [MediaQuery] directly.
+  /// Querying [MediaQuery] directly. Preferred.
   ///
   /// ```dart
   /// final Brightness brightness = MediaQuery.platformBrightnessOf(context);
@@ -214,7 +215,6 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// {@end-tool}
   ///
   /// See [Window.onPlatformBrightnessChanged].
-  /// {@endtemplate}
   @protected
   void handlePlatformBrightnessChanged() { }
 

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

@@ -1673,6 +1673,11 @@ class OpacityLayer extends ContainerLayer {
 }
 
 /// A composited layer that applies a shader to its children.
+///
+/// The shader is only applied inside the given [maskRect]. The shader itself
+/// uses the top left of the [maskRect] as its origin.
+///
+/// The [maskRect] does not affect the positions of any child layers.
 class ShaderMaskLayer extends ContainerLayer {
   /// Creates a shader mask layer.
   ///
@@ -1688,8 +1693,16 @@ class ShaderMaskLayer extends ContainerLayer {
 
   /// The shader to apply to the children.
   ///
+  /// The origin of the shader (e.g. of the coordinate system used by the `from`
+  /// and `to` arguments to [ui.Gradient.linear]) is at the top left of the
+  /// [maskRect].
+  ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
+  ///
+  /// See also:
+  ///
+  ///  * [ui.Gradient] and [ui.ImageShader], two shader types that can be used.
   Shader get shader => _shader;
   Shader _shader;
   set shader(Shader value) {
@@ -1699,7 +1712,10 @@ class ShaderMaskLayer extends ContainerLayer {
     }
   }
 
-  /// The size of the shader.
+  /// The position and size of the shader.
+  ///
+  /// The [shader] is only rendered inside this rectangle, using the top left of
+  /// the rectangle as its origin.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
@@ -1730,6 +1746,7 @@ class ShaderMaskLayer extends ContainerLayer {
     assert(shader != null);
     assert(maskRect != null);
     assert(blendMode != null);
+    assert(layerOffset != null);
     final Rect shiftedMaskRect = layerOffset == Offset.zero ? maskRect : maskRect.shift(layerOffset);
     engineLayer = builder.pushShaderMask(shader, shiftedMaskRect, blendMode, oldLayer: _engineLayer);
     addChildrenToScene(builder, layerOffset);

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

@@ -968,6 +968,9 @@ class RenderShaderMask extends RenderProxyBox {
   ///
   /// The shader callback is called with the current size of the child so that
   /// it can customize the shader to the size and location of the child.
+  ///
+  /// The rectangle will always be at the origin when called by
+  /// [RenderShaderMask].
   // TODO(abarth): Use the delegate pattern here to avoid generating spurious
   // repaints when the ShaderCallback changes identity.
   ShaderCallback get shaderCallback => _shaderCallback;

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

@@ -214,7 +214,9 @@ abstract class WidgetsBindingObserver {
   ///    boilerplate.
   void didChangeTextScaleFactor() { }
 
-  /// {@macro on_platform_brightness_change}
+  /// Called when the platform brightness changes.
+  ///
+  /// This method exposes notifications from [Window.onPlatformBrightnessChanged].
   void didChangePlatformBrightness() { }
 
   /// Called when the system tells the app that the user's locale has