Samples for BoxDecoration and some related classes (#9902)

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

@@ -1811,6 +1811,41 @@ class RenderFractionalTranslation extends RenderProxyBox {
 ///
 /// The [hitTest] method is called when the user interacts with the underlying
 /// render object, to determine if the user hit the object or missed it.
+///
+/// ## Sample code
+///
+/// This sample extends the same code shown for [RadialGradient] to create a
+/// custom painter that paints a sky.
+///
+/// ```dart
+/// class Sky extends CustomPainter {
+///   @override
+///   void paint(Canvas canvas, Size size) {
+///     var rect = Offset.zero & size;
+///     var gradient = new RadialGradient(
+///       center: const FractionalOffset(0.7, 0.2),
+///       radius: 0.2,
+///       colors: [const Color(0xFFFFFF00), const Color(0xFF0099FF)],
+///       stops: [0.4, 1.0],
+///     );
+///     canvas.drawRect(
+///       rect,
+///       new Paint()..shader = gradient.createShader(rect),
+///     );
+///   }
+///
+///   @override
+///   bool shouldRepaint(CustomPainter oldDelegate) => false;
+/// }
+/// ```
+///
+/// See also:
+///
+///  * [Canvas], the class that a custom painter uses to paint.
+///  * [CustomPaint], the widget that uses [CustomPainter], and whose sample
+///    code shows how to use the above `Sky` class.
+///  * [RadialGradient], whose sample code section shows a different take
+///    on the sample code above.
 abstract class CustomPainter extends Listenable {
   /// Creates a custom painter.
   ///

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

@@ -198,10 +198,32 @@ class BackdropFilter extends SingleChildRenderObjectWidget {
 /// a child, they attempt to size themselves to the [size], which defaults to
 /// [Size.zero].
 ///
+/// ## Sample code
+///
+/// This example shows how the sample custom painter shown at [CustomPainter]
+/// could be used in a [CustomPaint] widget to display a background to some
+/// text.
+///
+/// ```dart
+/// new CustomPaint(
+///   painter: new Sky(),
+///   child: new Center(
+///     child: new Text(
+///       'Once upon a time...',
+///       style: const TextStyle(
+///         fontSize: 40.0,
+///         fontWeight: FontWeight.w900,
+///         color: const Color(0xFFFFFFFF),
+///       ),
+///     ),
+///   ),
+/// ),
+/// ```
+///
 /// See also:
 ///
-///  * [CustomPainter].
-///  * [Canvas].
+///  * [CustomPainter], the class to extend when creating custom painters.
+///  * [Canvas], the class that a custom painter uses to paint.
 class CustomPaint extends SingleChildRenderObjectWidget {
   /// Creates a widget that delegates its painting.
   const CustomPaint({ Key key, this.painter, this.foregroundPainter, this.size: Size.zero, Widget child })

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

@@ -16,10 +16,34 @@ import 'image.dart';
 /// not.
 ///
 /// Commonly used with [BoxDecoration].
-/// 
+///
+/// ## Sample code
+///
+/// This sample shows a radial gradient that draws a moon on a night sky:
+///
+/// ```dart
+/// new DecoratedBox(
+///   decoration: new BoxDecoration(
+///     gradient: new RadialGradient(
+///       center: const FractionalOffset(0.25, 0.3),
+///       radius: 0.15,
+///       colors: <Color>[
+///         const Color(0xFFEEEEEE),
+///         const Color(0xFF111133),
+///       ],
+///       stops: <double>[0.9, 1.0],
+///     ),
+///   ),
+/// ),
+/// ```
+///
 /// See also:
 ///
-/// * [DecoratedBoxTransition], the version of this class that animates on the [decoration] property.
+///  * [DecoratedBoxTransition], the version of this class that animates on the
+///    [decoration] property.
+///  * [Decoration], which you can extend to provide other effects with
+///    [DecoratedBox].
+///  * [CustomPaint], another way to draw custom effects from the widget layer.
 class DecoratedBox extends SingleChildRenderObjectWidget {
   /// Creates a widget that paints a [Decoration].
   ///