Explain that BoxDecoration doesn't do clip. (#26089)

Fixes https://github.com/flutter/flutter/issues/22370

packages/flutter/lib/src/painting/box_decoration.dart

@@ -54,6 +54,13 @@ import 'image_provider.dart';
 /// ```
 /// {@end-tool}
 ///
+/// {@template flutter.painting.boxDecoration.clip}
+/// The [shape] or the [borderRadius] won't clip the children of the
+/// decorated [Container]. If the clip is required, insert a clip widget
+/// (e.g., [ClipRect], [ClipRRect], [ClipPath]) as the child of the [Container].
+/// Be aware that clipping may be costly in terms of performance.
+/// {@endtemplate}
+///
 /// See also:
 ///
 ///  * [DecoratedBox] and [Container], widgets that can be configured with
@@ -130,6 +137,8 @@ class BoxDecoration extends Decoration {
   ///
   /// Applies only to boxes with rectangular shapes; ignored if [shape] is not
   /// [BoxShape.rectangle].
+  ///
+  /// {@macro flutter.painting.boxDecoration.clip}
   final BorderRadiusGeometry borderRadius;
 
   /// A list of shadows cast by this box behind the box.
@@ -163,6 +172,8 @@ class BoxDecoration extends Decoration {
   /// different [ShapeBorder]s; in particular, [CircleBorder] instead of
   /// [BoxShape.circle] and [RoundedRectangleBorder] instead of
   /// [BoxShape.rectangle].
+  ///
+  /// {@macro flutter.painting.boxDecoration.clip}
   final BoxShape shape;
 
   @override