Add Decoding Flutter videos to API docs (#116454)

* Add Decoding Flutter videos to API docs

* Review comments

* Update widget of the week videos too

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -3088,6 +3088,8 @@ mixin Diagnosticable {
 
   /// Add additional properties associated with the node.
   ///
+  /// {@youtube 560 315 https://www.youtube.com/watch?v=DnC7eT-vh1k}
+  ///
   /// Use the most specific [DiagnosticsProperty] existing subclass to describe
   /// each property instead of the [DiagnosticsProperty] base class. There are
   /// only a small number of [DiagnosticsProperty] subclasses each covering a

packages/flutter/lib/src/gestures/arena.dart

@@ -97,6 +97,10 @@ class _GestureArena {
   }
 }
 
+/// Used for disambiguating the meaning of sequences of pointer events.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=Q85LBtBdi0U}
+///
 /// The first member to accept or the last member to not reject wins.
 ///
 /// See <https://flutter.dev/gestures/#gesture-disambiguation> for more

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

@@ -602,6 +602,8 @@ class _MaterialStateUnderlineInputBorder extends MaterialStateUnderlineInputBord
 /// on a widget's interactive "state", which is defined as a set
 /// of [MaterialState]s.
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=CylXr3AF3uU}
+///
 /// Material state properties represent values that depend on a widget's material
 /// "state". The state is encoded as a set of [MaterialState] values, like
 /// [MaterialState.focused], [MaterialState.hovered], [MaterialState.pressed]. For

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

@@ -26,6 +26,8 @@ const double _kIndicatorWidth = 64;
 
 /// Material 3 Navigation Bar component.
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=DVGYddFaLv0}
+///
 /// Navigation bars offer a persistent and convenient way to switch between
 /// primary destinations in an app.
 ///

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

@@ -70,6 +70,8 @@ export 'package:flutter/services.dart' show Brightness;
 
 /// An interface that defines custom additions to a [ThemeData] object.
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=8-szcYzFVao}
+///
 /// Typically used for custom colors. To use, subclass [ThemeExtension],
 /// define a number of fields (e.g. [Color]s), and implement the [copyWith] and
 /// [lerp] methods. The latter will ensure smooth transitions of properties when

packages/flutter/lib/src/widgets/async.dart

@@ -439,11 +439,15 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
   Widget build(BuildContext context, AsyncSnapshot<T> currentSummary) => builder(context, currentSummary);
 }
 
-/// Widget that builds itself based on the latest snapshot of interaction with
+/// A widget that builds itself based on the latest snapshot of interaction with
 /// a [Future].
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=ek8ZPdWj4Qo}
+///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=zEdw_1B7JHY}
 ///
+/// ## Managing the future
+///
 /// The [future] must have been obtained earlier, e.g. during [State.initState],
 /// [State.didUpdateWidget], or [State.didChangeDependencies]. It must not be
 /// created during the [State.build] or [StatelessWidget.build] method call when
@@ -454,8 +458,6 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
 /// A general guideline is to assume that every `build` method could get called
 /// every frame, and to treat omitted calls as an optimization.
 ///
-/// {@youtube 560 315 https://www.youtube.com/watch?v=ek8ZPdWj4Qo}
-///
 /// ## Timing
 ///
 /// Widget rebuilding is scheduled by the completion of the future, using

packages/flutter/lib/src/widgets/framework.dart

@@ -1581,6 +1581,8 @@ abstract class ParentDataWidget<T extends ParentData> extends ProxyWidget {
 
 /// Base class for widgets that efficiently propagate information down the tree.
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=og-vJqLzg2c}
+///
 /// To obtain the nearest instance of a particular type of inherited widget from
 /// a build context, use [BuildContext.dependOnInheritedWidgetOfExactType].
 ///

packages/flutter/lib/src/widgets/media_query.dart

@@ -255,6 +255,8 @@ class MediaQueryData {
   /// level MediaQuery created by [WidgetsApp] are the same as the window
   /// (often the mobile device screen) that contains the app.
   ///
+  /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw}
+  ///
   /// See also:
   ///
   ///  * [ui.window], which provides some additional detail about this property
@@ -272,6 +274,8 @@ class MediaQueryData {
   ///
   /// Padding is derived from the values of [viewInsets] and [viewPadding].
   ///
+  /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw}
+  ///
   /// See also:
   ///
   ///  * [ui.window], which provides some additional detail about this
@@ -294,6 +298,8 @@ class MediaQueryData {
   /// same as the window that contains the app. On mobile devices, this will
   /// typically be the full screen.
   ///
+  /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw}
+  ///
   /// See also:
   ///
   ///  * [ui.window], which provides some additional detail about this

packages/flutter/lib/src/widgets/primary_scroll_controller.dart

@@ -17,6 +17,8 @@ const Set<TargetPlatform> _kMobilePlatforms = <TargetPlatform>{
 
 /// Associates a [ScrollController] with a subtree.
 ///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=33_0ABjFJUU}
+///
 /// When a [ScrollView] has [ScrollView.primary] set to true, the [ScrollView]
 /// uses [of] to inherit the [PrimaryScrollController] associated with its
 /// subtree.

packages/flutter/lib/src/widgets/scroll_view.dart

@@ -180,6 +180,12 @@ abstract class ScrollView extends StatelessWidget {
   /// [TargetPlatformVariant.mobile] for ScrollViews in the [Axis.vertical]
   /// scroll direction. Adding another to your app will override the
   /// PrimaryScrollController above it.
+  ///
+  /// The following video contains more information about scroll controllers,
+  /// the PrimaryScrollController widget, and their impact on your apps:
+  ///
+  /// {@youtube 560 315 https://www.youtube.com/watch?v=33_0ABjFJUU}
+  ///
   /// {@endtemplate}
   final bool? primary;