feat: Added more youtube refs to widgets docstrings (#96484)
diff --git a/packages/flutter/lib/src/cupertino/scrollbar.dart b/packages/flutter/lib/src/cupertino/scrollbar.dart
index 7e468fb..30dfa51 100644
--- a/packages/flutter/lib/src/cupertino/scrollbar.dart
+++ b/packages/flutter/lib/src/cupertino/scrollbar.dart
@@ -32,6 +32,8 @@
/// To add a scrollbar to a [ScrollView], simply wrap the scroll view widget in
/// a [CupertinoScrollbar] widget.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc}
+///
/// {@macro flutter.widgets.Scrollbar}
///
/// When dragging a [CupertinoScrollbar] thumb, the thickness and radius will
diff --git a/packages/flutter/lib/src/foundation/isolates.dart b/packages/flutter/lib/src/foundation/isolates.dart
index 576207b..8a1c151 100644
--- a/packages/flutter/lib/src/foundation/isolates.dart
+++ b/packages/flutter/lib/src/foundation/isolates.dart
@@ -26,9 +26,11 @@
/// few milliseconds, consider [SchedulerBinding.scheduleTask] instead.
///
/// {@template flutter.foundation.compute.types}
-/// `Q` is the type of the message that kicks off the computation.
+/// The [compute] method accepts the following parameters:
///
-/// `R` is the type of the value returned.
+/// * `Q` is the type of the message that kicks off the computation.
+///
+/// * `R` is the type of the value returned.
/// {@endtemplate}
///
/// The `callback` argument must be a top-level function, not a closure or an
@@ -44,7 +46,11 @@
/// [Timeline]. This is useful when profiling an application.
typedef ComputeImpl = Future<R> Function<Q, R>(ComputeCallback<Q, R> callback, Q message, { String? debugLabel });
-/// A function that spawns an isolate and runs a callback on that isolate.
+/// A function that spawns an isolate and runs a callback on that isolate. This
+/// method should be used to execute parallel tasks that reduce the risk of
+/// skipping frames.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=5AxWC49ZMzs}
///
/// See also:
///
diff --git a/packages/flutter/lib/src/material/expansion_panel.dart b/packages/flutter/lib/src/material/expansion_panel.dart
index b82d76b..60c5587 100644
--- a/packages/flutter/lib/src/material/expansion_panel.dart
+++ b/packages/flutter/lib/src/material/expansion_panel.dart
@@ -58,6 +58,8 @@
/// expanded or collapsed. The body of the panel is only visible when it is
/// expanded.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=2aJZzRMziJc}
+///
/// Expansion panels are only intended to be used as children for
/// [ExpansionPanelList].
///
diff --git a/packages/flutter/lib/src/material/refresh_indicator.dart b/packages/flutter/lib/src/material/refresh_indicator.dart
index 70e0795..f76e6fe 100644
--- a/packages/flutter/lib/src/material/refresh_indicator.dart
+++ b/packages/flutter/lib/src/material/refresh_indicator.dart
@@ -60,6 +60,8 @@
/// A widget that supports the Material "swipe to refresh" idiom.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=ORApMlzwMdM}
+///
/// When the child's [Scrollable] descendant overscrolls, an animated circular
/// progress indicator is faded into view. When the scroll ends, if the
/// indicator has been dragged far enough for it to become completely opaque,
diff --git a/packages/flutter/lib/src/material/scrollbar.dart b/packages/flutter/lib/src/material/scrollbar.dart
index b56fa1a..98aac54 100644
--- a/packages/flutter/lib/src/material/scrollbar.dart
+++ b/packages/flutter/lib/src/material/scrollbar.dart
@@ -23,6 +23,8 @@
/// To add a scrollbar to a [ScrollView], wrap the scroll view
/// widget in a [Scrollbar] widget.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc}
+///
/// {@macro flutter.widgets.Scrollbar}
///
/// Dynamically changes to an iOS style scrollbar that looks like
diff --git a/packages/flutter/lib/src/material/tabs.dart b/packages/flutter/lib/src/material/tabs.dart
index e1504a4..469c254 100644
--- a/packages/flutter/lib/src/material/tabs.dart
+++ b/packages/flutter/lib/src/material/tabs.dart
@@ -1551,6 +1551,8 @@
/// Displays a row of small circular indicators, one per tab.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=Q628ue9Cq7U}
+///
/// The selected tab's indicator is highlighted. Often used in conjunction with
/// a [TabBarView].
///
diff --git a/packages/flutter/lib/src/material/theme.dart b/packages/flutter/lib/src/material/theme.dart
index 4e717ed..aec9612 100644
--- a/packages/flutter/lib/src/material/theme.dart
+++ b/packages/flutter/lib/src/material/theme.dart
@@ -18,6 +18,8 @@
///
/// A theme describes the colors and typographic choices of an application.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=oTvQDJOBXmM}
+///
/// Descendant widgets obtain the current theme's [ThemeData] object using
/// [Theme.of]. When a widget uses [Theme.of], it is automatically rebuilt if
/// the theme later changes, so that the changes can be applied.
diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart
index 851ad52..b42ae2d 100644
--- a/packages/flutter/lib/src/rendering/object.dart
+++ b/packages/flutter/lib/src/rendering/object.dart
@@ -1114,6 +1114,8 @@
/// The [RenderObject] class hierarchy is the core of the rendering
/// library's reason for being.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=zmbmrw07qBc}
+///
/// [RenderObject]s have a [parent], and have a slot called [parentData] in
/// which the parent [RenderObject] can store child-specific data, for example,
/// the child position. The [RenderObject] class also implements the basic
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index cf25026..2b08817 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -4832,6 +4832,8 @@
/// case is typically to remove the [Expanded] or [Flexible] widgets from around
/// the inner children.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=jckqXR5CrPI}
+///
/// For more discussion about constraints, see [BoxConstraints].
///
/// ### The yellow and black striped banner
@@ -6155,6 +6157,8 @@
/// A widget that tracks the movement of mice.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=1oF3pI5umck}
+///
/// [MouseRegion] is used
/// when it is needed to compare the list of objects that a mouse pointer is
/// hovering over between this frame and the last frame. This means entering
diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
index 27eb800..08a6b45 100644
--- a/packages/flutter/lib/src/widgets/framework.dart
+++ b/packages/flutter/lib/src/widgets/framework.dart
@@ -438,14 +438,6 @@
/// * Use `const` widgets where possible, and provide a `const` constructor for
/// the widget so that users of the widget can also do so.
///
-/// * When trying to create a reusable piece of UI, prefer using a widget
-/// rather than a helper method. For example, if there was a function used to
-/// build a widget, a [State.setState] call would require Flutter to entirely
-/// rebuild the returned wrapping widget. If a [Widget] was used instead,
-/// Flutter would be able to efficiently re-render only those parts that
-/// really need to be updated. Even better, if the created widget is `const`,
-/// Flutter would short-circuit most of the rebuild work.
-///
/// * Consider refactoring the stateless widget into a stateful widget so that
/// it can use some of the techniques described at [StatefulWidget], such as
/// caching common parts of subtrees and using [GlobalKey]s when changing the
@@ -459,6 +451,20 @@
/// part of the build function that builds the inner-most widget into its own
/// widget, so that only the inner-most widget needs to be rebuilt when the
/// theme changes.
+/// {@template flutter.flutter.widgets.framework.prefer_const_over_helper}
+/// * When trying to create a reusable piece of UI, prefer using a widget
+/// rather than a helper method. For example, if there was a function used to
+/// build a widget, a [State.setState] call would require Flutter to entirely
+/// rebuild the returned wrapping widget. If a [Widget] was used instead,
+/// Flutter would be able to efficiently re-render only those parts that
+/// really need to be updated. Even better, if the created widget is `const`,
+/// Flutter would short-circuit most of the rebuild work.
+/// {@endtemplate}
+///
+/// This video gives more explainations on why `const` constructors are important
+/// and why a [Widget] is better than a helper method.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=IOyq-eTRhvo}
///
/// {@tool snippet}
///
@@ -650,24 +656,16 @@
/// this ideal, the more efficient it will be.)
///
/// * If a subtree does not change, cache the widget that represents that
-/// subtree and re-use it each time it can be used. It is massively more
-/// efficient for a widget to be re-used than for a new (but
-/// identically-configured) widget to be created. Factoring out the stateful
-/// part into a widget that takes a child argument is a common way of doing
-/// this. Another caching strategy consists of assigning a widget to a
-/// `final` state variable which can be used in the build method.
+/// subtree and re-use it each time it can be used. To do this, simply assign
+/// a widget to a `final` state variable and re-use it in the build method. It
+/// is massively more efficient for a widget to be re-used than for a new (but
+/// identically-configured) widget to be created. Another caching stragegy
+/// consists in extracting the mutable part of the widget into a [StatefulWidget]
+/// which accepts a child parameter.
///
/// * Use `const` widgets where possible. (This is equivalent to caching a
/// widget and re-using it.)
///
-/// * When trying to create a reusable piece of UI, prefer using a widget
-/// rather than a helper method. For example, if there was a function used to
-/// build a widget, a [State.setState] call would require Flutter to entirely
-/// rebuild the returned wrapping widget. If a [Widget] was used instead,
-/// Flutter would be able to efficiently re-render only those parts that
-/// really need to be updated. Even better, if the created widget is `const`,
-/// Flutter would short-circuit most of the rebuild work.
-///
/// * Avoid changing the depth of any created subtrees or changing the type of
/// any widgets in the subtree. For example, rather than returning either the
/// child or the child wrapped in an [IgnorePointer], always wrap the child
@@ -684,6 +682,13 @@
/// [KeyedSubtree] widget may be useful for this purpose if no other widget
/// can conveniently be assigned the key.)
///
+/// {@macro flutter.flutter.widgets.framework.prefer_const_over_helper}
+///
+/// This video gives more explainations on why `const` constructors are important
+/// and why a [Widget] is better than a helper method.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=IOyq-eTRhvo}
+///
/// {@tool snippet}
///
/// This is a skeleton of a stateful widget subclass called `YellowBird`.
@@ -2065,6 +2070,8 @@
/// the methods on this class should not be cached beyond the execution of a
/// single synchronous function.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=rIaaH87z1-g}
+///
/// [BuildContext] objects are actually [Element] objects. The [BuildContext]
/// interface is used to discourage direct manipulation of [Element] objects.
abstract class BuildContext {
diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart
index bbdbbdd..67beb0a 100644
--- a/packages/flutter/lib/src/widgets/gesture_detector.dart
+++ b/packages/flutter/lib/src/widgets/gesture_detector.dart
@@ -114,6 +114,8 @@
/// If this widget has a child, it defers to that child for its sizing behavior.
/// If it does not have a child, it grows to fit the parent instead.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=WhVXkCFPmK4}
+///
/// By default a GestureDetector with an invisible child ignores touches;
/// this behavior can be controlled with [behavior].
///
diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart
index ad78e2b..923a207 100644
--- a/packages/flutter/lib/src/widgets/scroll_view.dart
+++ b/packages/flutter/lib/src/widgets/scroll_view.dart
@@ -237,6 +237,8 @@
/// scroll view needs to be recomputed whenever the scroll position changes.
///
/// Defaults to false.
+ ///
+ /// {@youtube 560 315 https://www.youtube.com/watch?v=LUqDNnv_dh0}
/// {@endtemplate}
final bool shrinkWrap;
diff --git a/packages/flutter/lib/src/widgets/scrollbar.dart b/packages/flutter/lib/src/widgets/scrollbar.dart
index 48568c6..488e36d 100644
--- a/packages/flutter/lib/src/widgets/scrollbar.dart
+++ b/packages/flutter/lib/src/widgets/scrollbar.dart
@@ -760,6 +760,8 @@
/// To add a scrollbar to a [ScrollView], like a [ListView] or a
/// [CustomScrollView], wrap the scroll view widget in a [RawScrollbar] widget.
///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc}
+///
/// {@template flutter.widgets.Scrollbar}
/// A scrollbar thumb indicates which portion of a [ScrollView] is actually
/// visible.
