Update Theme documentation with Cupertino details (#161980)

Updates `Theme` documentation to note how it interacts with descendant
`Cupertino` widgets.

Fixes #161573

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: Renzo Olivares <[email protected]>

Author: Renzo-Olivares

packages/flutter/lib/src/material/text_selection_theme.dart

@@ -53,7 +53,8 @@ class TextSelectionThemeData with Diagnosticable {
   ///
   /// On iOS [TextField] and [SelectableText] cannot access [selectionHandleColor].
   /// To set the [selectionHandleColor] on iOS, you can change the
-  /// [CupertinoThemeData.primaryColor] in [ThemeData.cupertinoOverrideTheme].
+  /// [CupertinoThemeData.primaryColor] by wrapping the subtree containing
+  /// your [TextField] or [SelectableText] with a [CupertinoTheme].
   final Color? selectionHandleColor;
 
   /// Creates a copy of this object with the given fields replaced with the

packages/flutter/lib/src/material/theme.dart

@@ -32,6 +32,14 @@ const Duration kThemeAnimationDuration = Duration(milliseconds: 200);
 /// The [Theme] widget implies an [IconTheme] widget, set to the value of the
 /// [ThemeData.iconTheme] of the [data] for the [Theme].
 ///
+/// To interact seamlessly with descendant Cupertino widgets, the [Theme] widget
+/// provides a [CupertinoTheme] for its descendants with a [CupertinoThemeData] inherited
+/// from the nearest ancestor [CupertinoTheme] or if none exists, derived from the
+/// Material [data] for the [Theme]. The values in the Material derived [CupertinoThemeData]
+/// are overridable through [ThemeData.cupertinoOverrideTheme]. The values from an
+/// inherited [CupertinoThemeData] can be overriden by wrapping the desired subtree
+/// with a [CupertinoTheme].
+///
 /// See also:
 ///
 ///  * [ThemeData], which describes the actual configuration of a theme.