Document stack's clipping behaviour better (#130749)
Fixes https://github.com/flutter/flutter/issues/40216
diff --git a/packages/flutter/lib/src/rendering/stack.dart b/packages/flutter/lib/src/rendering/stack.dart
index bb2e3c9..fb8aa3f 100644
--- a/packages/flutter/lib/src/rendering/stack.dart
+++ b/packages/flutter/lib/src/rendering/stack.dart
@@ -435,7 +435,16 @@
/// {@macro flutter.material.Material.clipBehavior}
///
- /// Defaults to [Clip.hardEdge], and must not be null.
+ /// Stacks only clip children whose geometry overflow the stack. A child that
+ /// paints outside its bounds (e.g. a box with a shadow) will not be clipped,
+ /// regardless of the value of this property. Similarly, a child that itself
+ /// has a descendant that overflows the stack will not be clipped, as only the
+ /// geometry of the stack's direct children are considered.
+ ///
+ /// To clip children whose geometry does not overflow the stack, consider
+ /// using a [RenderClipRect] render object.
+ ///
+ /// Defaults to [Clip.hardEdge].
Clip get clipBehavior => _clipBehavior;
Clip _clipBehavior = Clip.hardEdge;
set clipBehavior(Clip value) {
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index 3dc2786..dafcd12 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -3914,6 +3914,15 @@
/// {@macro flutter.material.Material.clipBehavior}
///
+ /// Stacks only clip children whose geometry overflow the stack. A child that
+ /// paints outside its bounds (e.g. a box with a shadow) will not be clipped,
+ /// regardless of the value of this property. Similarly, a child that itself
+ /// has a descendant that overflows the stack will not be clipped, as only the
+ /// geometry of the stack's direct children are considered.
+ ///
+ /// To clip children whose geometry does not overflow the stack, consider
+ /// using a [ClipRect] widget.
+ ///
/// Defaults to [Clip.hardEdge].
final Clip clipBehavior;
