Improve docs to address flutter/flutter#31202 (#31454)
## Description
Clarify that ClipRect can be added to ensure that CustomPainter will be drawing within bounds.
## Related Issues
https://github.com/flutter/flutter/issues/31202
diff --git a/packages/flutter/lib/src/rendering/custom_paint.dart b/packages/flutter/lib/src/rendering/custom_paint.dart
index f8a9e46..b0fb6db 100644
--- a/packages/flutter/lib/src/rendering/custom_paint.dart
+++ b/packages/flutter/lib/src/rendering/custom_paint.dart
@@ -157,8 +157,13 @@
/// coordinate space configured such that the origin is at the top left of the
/// box. The area of the box is the size of the [size] argument.
///
- /// Paint operations should remain inside the given area. Graphical operations
- /// outside the bounds may be silently ignored, clipped, or not clipped.
+ /// Paint operations should remain inside the given area. Graphical
+ /// operations outside the bounds may be silently ignored, clipped, or not
+ /// clipped. It may sometimes be difficult to guarantee that a certain
+ /// operation is inside the bounds (e.g., drawing a rectangle whose size is
+ /// determined by user inputs). In that case, consider calling
+ /// [Canvas.clipRect] at the beginning of [paint] so everything that follows
+ /// will be guaranteed to only draw within the clipped area.
///
/// Implementations should be wary of correctly pairing any calls to
/// [Canvas.save]/[Canvas.saveLayer] and [Canvas.restore], otherwise all
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index 3bfcfb4..b48e0b9 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -419,7 +419,9 @@
/// painters are expected to paint within a rectangle starting at the origin and
/// encompassing a region of the given size. (If the painters paint outside
/// those bounds, there might be insufficient memory allocated to rasterize the
-/// painting commands and the resulting behavior is undefined.)
+/// painting commands and the resulting behavior is undefined.) To enforce
+/// painting within those bounds, consider wrapping this [CustomPaint] with a
+/// [ClipRect] widget.
///
/// Painters are implemented by subclassing [CustomPainter].
///
