[cupertino_ui] Migrate api sample code to @example dartdoc directive

analysis_options.yaml

@@ -16,6 +16,9 @@ analyzer:
     # something (https://github.com/flutter/flutter/issues/143312)
     deprecated_member_use: ignore
     deprecated_member_use_from_same_package: ignore
+    # `dart analyze` hasn't recognized the @example directive yet.
+    # Remove it once https://github.com/dart-lang/sdk/pull/63646 is landed.
+    doc_directive_unknown: ignore
   exclude: # DIFFERENT FROM FLUTTER/FLUTTER
     # Ignore generated files
     - '**/*.pb.dart'

packages/cupertino_ui/example/analysis_options.yaml

@@ -1,5 +1,3 @@
-# This file is also used by dev/bots/analyze_snippet_code.dart to analyze code snippets (`{@tool snippet}` sections).
-
 # The following line activates a set of recommended lints for Flutter apps,
 # packages, and plugins designed to encourage good coding practices.
 analyzer:

packages/cupertino_ui/lib/src/activity_indicator.dart

@@ -21,11 +21,14 @@ const Color _kActiveTickColor = CupertinoDynamicColor.withBrightness(
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=AENVH-ZqKDQ}
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This example shows how [CupertinoActivityIndicator] can be customized.
 ///
-/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_activity_indicator.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///
@@ -201,11 +204,14 @@ class _CupertinoActivityIndicatorPainter extends CustomPainter {
 /// The [CupertinoLinearActivityIndicator] is a linear progress bar that
 /// displays a colored bar to indicate the progress of an ongoing task.
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This example shows how [CupertinoLinearActivityIndicator] can be customized.
 ///
-/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_linear_activity_indicator.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/activity_indicator/cupertino_linear_activity_indicator.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///

packages/cupertino_ui/lib/src/app.dart

@@ -67,7 +67,11 @@ import 'theme.dart';
 ///  * The San Francisco font family is unavailable on Android and can result
 ///    in undefined font behavior.
 ///
-/// {@tool snippet}
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 /// This example shows how to create a [CupertinoApp] that disables the "debug"
 /// banner with a [home] route that will be displayed when the app is launched.
 ///
@@ -84,9 +88,14 @@ import 'theme.dart';
 ///   debugShowCheckedModeBanner: false,
 /// )
 /// ```
-/// {@end-tool}
 ///
-/// {@tool snippet}
+// TODO(framework): End of the blue example container.
+///
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 /// This example shows how to create a [CupertinoApp] that uses the [routes]
 /// `Map` to define the "home" route and an "about" route.
 ///
@@ -112,9 +121,14 @@ import 'theme.dart';
 ///   },
 /// )
 /// ```
-/// {@end-tool}
 ///
-/// {@tool snippet}
+// TODO(framework): End of the blue example container.
+///
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 /// This example shows how to create a [CupertinoApp] that defines a [theme] that
 /// will be used for Cupertino widgets in the app.
 ///
@@ -134,7 +148,8 @@ import 'theme.dart';
 ///   ),
 /// )
 /// ```
-/// {@end-tool}
+///
+// TODO(framework): End of the blue example container.
 ///
 /// See also:
 ///
@@ -357,7 +372,11 @@ class CupertinoApp extends StatefulWidget {
   final bool debugShowCheckedModeBanner;
 
   /// {@macro flutter.widgets.widgetsApp.shortcuts}
-  /// {@tool snippet}
+  // TODO(framework): Replace the following block with a blue example container
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+  // TODO(framework): Add unit tests to this code snippet.
+  // https://github.com/flutter/flutter/issues/188530
+  ///
   /// This example shows how to add a single shortcut for
   /// [LogicalKeyboardKey.select] to the default shortcuts without needing to
   /// add your own [Shortcuts] widget.
@@ -380,12 +399,17 @@ class CupertinoApp extends StatefulWidget {
   ///   );
   /// }
   /// ```
-  /// {@end-tool}
+  ///
+  // TODO(framework): End of the blue example container.
   /// {@macro flutter.widgets.widgetsApp.shortcuts.seeAlso}
   final Map<ShortcutActivator, Intent>? shortcuts;
 
   /// {@macro flutter.widgets.widgetsApp.actions}
-  /// {@tool snippet}
+  // TODO(framework): Replace the following block with a blue example container
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+  // TODO(framework): Add unit tests to this code snippet.
+  // https://github.com/flutter/flutter/issues/188530
+  ///
   /// This example shows how to add a single action handling an
   /// [ActivateAction] to the default actions without needing to
   /// add your own [Actions] widget.
@@ -413,7 +437,8 @@ class CupertinoApp extends StatefulWidget {
   ///   );
   /// }
   /// ```
-  /// {@end-tool}
+  ///
+  // TODO(framework): End of the blue example container.
   /// {@macro flutter.widgets.widgetsApp.actions.seeAlso}
   final Map<Type, Action<Intent>>? actions;
 

packages/cupertino_ui/lib/src/bottom_tab_bar.dart

@@ -46,11 +46,14 @@ const Color _kDefaultTabBarInactiveColor = CupertinoColors.inactiveGray;
 /// this behavior, wrap each of the `navigationBar`'s components inside a
 /// [MediaQuery] with the desired [TextScaler].
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This example shows a [CupertinoTabBar] placed in a [CupertinoTabScaffold].
 ///
-/// ** See code in examples/api/lib/cupertino/bottom_tab_bar/cupertino_tab_bar.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/bottom_tab_bar/cupertino_tab_bar.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///

packages/cupertino_ui/lib/src/button.dart

@@ -58,12 +58,15 @@ enum _CupertinoButtonStyle {
 /// with the [CupertinoThemeData.primaryColor] (or
 /// [CupertinoThemeData.primaryContrastingColor] if the button is disabled).
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This sample shows produces an enabled and disabled [CupertinoButton] and
 /// [CupertinoButton.filled].
 ///
-/// ** See code in examples/api/lib/cupertino/button/cupertino_button.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/button/cupertino_button.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///

packages/cupertino_ui/lib/src/checkbox.dart

@@ -73,11 +73,14 @@ const List<double> _kDisabledDarkGradientOpacities = <double>[0.08, 0.14];
 ///     [kMinInteractiveDimensionCupertino] pixels to meet accessibility
 ///     guidelines.
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This example shows a toggleable [CupertinoCheckbox].
 ///
-/// ** See code in examples/api/lib/cupertino/checkbox/cupertino_checkbox.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/checkbox/cupertino_checkbox.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///
@@ -202,7 +205,11 @@ class CupertinoCheckbox extends StatefulWidget {
   ///  * [WidgetState.focused].
   ///  * [WidgetState.disabled].
   ///
-  /// {@tool snippet}
+  // TODO(framework): Replace the following block with a blue example container
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+  // TODO(framework): Add unit tests to this code snippet.
+  // https://github.com/flutter/flutter/issues/188530
+  ///
   /// This example resolves the [fillColor] based on the current [WidgetState]
   /// of the [CupertinoCheckbox], providing a different [Color] when it is
   /// [WidgetState.disabled].
@@ -219,7 +226,8 @@ class CupertinoCheckbox extends StatefulWidget {
   ///   })
   /// )
   /// ```
-  /// {@end-tool}
+  ///
+  // TODO(framework): End of the blue example container.
   /// {@endtemplate}
   ///
   /// If [fillColor] resolves to null for the requested state, then the fill color

packages/cupertino_ui/lib/src/colors.dart

@@ -661,7 +661,11 @@ abstract final class CupertinoColors {
 /// [CupertinoDynamicColor.resolve] against its own [BuildContext], on a best-effort
 /// basis.
 ///
-/// {@tool snippet}
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 /// By default a [CupertinoButton] has no background color. The following sample
 /// code shows how to build a [CupertinoButton] that appears white in light mode,
 /// and changes automatically to black in dark mode.
@@ -677,7 +681,8 @@ abstract final class CupertinoColors {
 ///   child: child,
 /// )
 /// ```
-/// {@end-tool}
+///
+// TODO(framework): End of the blue example container.
 ///
 /// ### Using a [CupertinoDynamicColor] from a [CupertinoTheme]
 ///
@@ -686,7 +691,11 @@ abstract final class CupertinoColors {
 /// implicitly resolves all the colors used in the retrieved [CupertinoThemeData],
 /// before returning it.
 ///
-/// {@tool snippet}
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 /// The following code sample creates a [Container] with the `primaryColor` of the
 /// current theme. If `primaryColor` is a [CupertinoDynamicColor], the container
 /// will be adaptive, thanks to [CupertinoTheme.of]: it will switch to `primaryColor`'s
@@ -701,7 +710,8 @@ abstract final class CupertinoColors {
 ///   color: CupertinoTheme.of(context).primaryColor,
 /// )
 /// ```
-/// {@end-tool}
+///
+// TODO(framework): End of the blue example container.
 ///
 /// ### Manually Resolving a [CupertinoDynamicColor]
 ///
@@ -712,7 +722,11 @@ abstract final class CupertinoColors {
 /// the colors used in the [Border] have to be resolved manually before being passed
 /// to [CupertinoNavigationBar]'s constructor.
 ///
-/// {@tool snippet}
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(framework): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530
+///
 ///
 /// The following code samples demonstrate two cases where you have to manually
 /// resolve a [CupertinoDynamicColor].
@@ -735,7 +749,8 @@ abstract final class CupertinoColors {
 ///   color: CupertinoDynamicColor.resolve(CupertinoColors.systemBlue, context),
 /// )
 /// ```
-/// {@end-tool}
+///
+// TODO(framework): End of the blue example container.
 ///
 /// See also:
 ///

packages/cupertino_ui/lib/src/context_menu.dart

@@ -96,19 +96,25 @@ enum _ContextMenuLocation { center, left, right }
 /// background or by calling `Navigator.pop(context)`. Unlike [PopupRoute], it can
 /// also be closed by swiping downwards.
 ///
-/// {@tool dartpad}
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+///
 /// This sample shows a very simple [CupertinoContextMenu] for the Flutter logo.
 /// Long press on it to open.
 ///
-/// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/context_menu/cupertino_context_menu.0.dart}
+///
+// TODO(framework): End of the @dartpad directive.
+///
+// TODO(framework): Replace the following block with a @dartpad directive
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
 ///
-/// {@tool dartpad}
 /// This sample shows a similar CupertinoContextMenu, this time using [builder]
 /// to add a border radius to the widget.
 ///
-/// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.1.dart **
-/// {@end-tool}
+/// {@example /example/lib/context_menu/cupertino_context_menu.1.dart}
+///
+// TODO(framework): End of the @dartpad directive.
 ///
 /// See also:
 ///
@@ -142,7 +148,11 @@ class CupertinoContextMenu extends StatefulWidget {
   /// Exposes the default border radius for matching iOS 16.0 behavior. This
   /// value was eyeballed from the iOS simulator running iOS 16.0.
   ///
-  /// {@tool snippet}
+  // TODO(framework): Replace the following block with a blue example container
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+  // TODO(framework): Add unit tests to this code snippet.
+  // https://github.com/flutter/flutter/issues/188530
+  ///
   ///
   /// Below is example code in order to match the default border radius for an
   /// iOS 16.0 open preview.
@@ -205,7 +215,8 @@ class CupertinoContextMenu extends StatefulWidget {
   /// )
   /// ```
   ///
-  /// {@end-tool}
+  ///
+  // TODO(framework): End of the blue example container.
   static const double kOpenBorderRadius = _previewBorderRadiusRatio;
 
   /// Exposes the final box shadow of the opening animation of the child widget
@@ -248,7 +259,11 @@ class CupertinoContextMenu extends StatefulWidget {
   /// the widget from 0 to [animationOpensAt], and the second stage for when the
   /// widget fully opens up to the menu, from [animationOpensAt] to 1.
   ///
-  /// {@tool snippet}
+  // TODO(framework): Replace the following block with a blue example container
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+  // TODO(framework): Add unit tests to this code snippet.
+  // https://github.com/flutter/flutter/issues/188530
+  ///
   ///
   /// Below is an example of using [builder] to show an image tile setup to be
   /// opened in the default way to match a native iOS 16.0 app. The behavior
@@ -314,9 +329,12 @@ class CupertinoContextMenu extends StatefulWidget {
   /// )
   /// ```
   ///
-  /// {@end-tool}
   ///
-  /// {@tool dartpad}
+  // TODO(framework): End of the blue example container.
+  ///
+  // TODO(framework): Replace the following block with a @dartpad directive
+  // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
+  ///
   /// Additionally below is an example of a real world use case for [builder].
   ///
   /// If a widget is passed to the [child] parameter with properties that
@@ -327,8 +345,9 @@ class CupertinoContextMenu extends StatefulWidget {
   /// like [CupertinoContextMenu.kEndBoxShadow], to match the native iOS
   /// animation as close as desired.
   ///
-  /// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.1.dart **
-  /// {@end-tool}
+  /// {@example /example/lib/context_menu/cupertino_context_menu.1.dart}
+  ///
+  // TODO(framework): End of the @dartpad directive.
   final CupertinoContextMenuBuilder builder;
 
   // TODO(mitchgoodwin): deprecate [child] with builder refactor https://github.com/flutter/flutter/issues/116306