Improve Cupertino docs (#72927)

* Add 'See also' to cupertino library

* Add snippets to CupertinoApp

* Add CupertinoPageScaffold samples

* Revert "Add CupertinoPageScaffold samples"

This reverts commit 01b0adf351f0320af7835551102d62e3416f0eab.

* Revert "Revert "Add CupertinoPageScaffold samples""

This reverts commit 0af506237a16f7fec5f3744a9bd015a511a15f72.

* Add CupertinoNavigationBar sample

* Tweak CupertinoPageScaffold sample

* Don't use Material in cupertino samples

* Fix colors

* Fix capitalization
Co-authored-by: Shi-Hao Hong <shihaohong@google.com>

* Apply suggestions from code review
Co-authored-by: Shi-Hao Hong <shihaohong@google.com>

* Add comment about backgroundColor
Co-authored-by: Shi-Hao Hong <shihaohong@google.com>

packages/flutter/lib/cupertino.dart

@@ -12,6 +12,14 @@
 /// Design](https://flutter.dev/docs/development/ui/widgets/material) set.
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=3PdUaidHc-E}
+///
+/// See also:
+///
+///  * [flutter.dev/widgets/cupertino](https://flutter.dev/docs/development/ui/widgets/cupertino)
+///    for a catalog of all Cupertino widgets.
+///  * [flutter.dev/widgets](https://flutter.dev/widgets/)
+///    for a catalog of commonly-used Flutter widgets.
+
 library cupertino;
 
 export 'src/cupertino/action_sheet.dart';

packages/flutter/lib/src/cupertino/app.dart

@@ -46,6 +46,75 @@ import 'theme.dart';
 ///  * The San Francisco font family is unavailable on Android and can result
 ///    in undefined font behavior.
 ///
+/// {@tool snippet}
+/// 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.
+///
+/// ![The CupertinoApp displays a CupertinoPageScaffold](https://flutter.github.io/assets-for-api-docs/assets/cupertino/basic_cupertino_app.png)
+///
+/// ```dart
+/// CupertinoApp(
+///   home: CupertinoPageScaffold(
+///     navigationBar: CupertinoNavigationBar(
+///       middle: const Text('Home'),
+///     ),
+///     child: Center(child: Icon(CupertinoIcons.share)),
+///   ),
+///   debugShowCheckedModeBanner: false,
+/// )
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet}
+/// This example shows how to create a [CupertinoApp] that uses the [routes]
+/// `Map` to define the "home" route and an "about" route.
+///
+/// ```dart
+/// CupertinoApp(
+///   routes: <String, WidgetBuilder>{
+///     '/': (BuildContext context) {
+///       return CupertinoPageScaffold(
+///         navigationBar: CupertinoNavigationBar(
+///           middle: const Text('Home Route'),
+///         ),
+///         child: Center(child: Icon(CupertinoIcons.share)),
+///       );
+///     },
+///     '/about': (BuildContext context) {
+///       return CupertinoPageScaffold(
+///         navigationBar: CupertinoNavigationBar(
+///           middle: const Text('About Route'),
+///         ),
+///         child: Center(child: Icon(CupertinoIcons.share)),
+///       );
+///     }
+///   },
+/// )
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet}
+/// This example shows how to create a [CupertinoApp] that defines a [theme] that
+/// will be used for Cupertino widgets in the app.
+///
+/// ![The CupertinoApp displays a CupertinoPageScaffold with orange-colored icons](https://flutter.github.io/assets-for-api-docs/assets/cupertino/theme_cupertino_app.png)
+///
+/// ```dart
+/// CupertinoApp(
+///   theme: CupertinoThemeData(
+///     brightness: Brightness.dark,
+///     primaryColor: CupertinoColors.systemOrange,
+///   ),
+///   home: CupertinoPageScaffold(
+///     navigationBar: CupertinoNavigationBar(
+///       middle: const Text('CupertinoApp Theme'),
+///     ),
+///     child: Center(child: Icon(CupertinoIcons.share)),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [CupertinoPageScaffold], which provides a standard page layout default

packages/flutter/lib/src/cupertino/nav_bar.dart

@@ -197,6 +197,33 @@ bool _isTransitionable(BuildContext context) {
 /// value from the operating system can be retrieved in many ways, such as querying
 /// [MediaQuery.textScaleFactorOf] against [CupertinoApp]'s [BuildContext].
 ///
+/// {@tool dartpad --template=stateful_widget_cupertino}
+/// This example shows a [CupertinoNavigationBar] placed in a [CupertinoPageScaffold].
+/// Since [backgroundColor]'s opacity is not 1.0, there is a blur effect and
+/// content slides underneath.
+///
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return CupertinoPageScaffold(
+///     navigationBar: CupertinoNavigationBar(
+///       // Try removing opacity to observe the lack of a blur effect and of sliding content.
+///       backgroundColor: CupertinoColors.systemGrey.withOpacity(0.5),
+///       middle: const Text('Sample Code'),
+///     ),
+///     child: Column(
+///       children: [
+///         Container(height: 50, color: CupertinoColors.systemRed),
+///         Container(height: 50, color: CupertinoColors.systemGreen),
+///         Container(height: 50, color: CupertinoColors.systemBlue),
+///         Container(height: 50, color: CupertinoColors.systemYellow),
+///       ],
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [CupertinoPageScaffold], a page layout helper typically hosting the

packages/flutter/lib/src/cupertino/page_scaffold.dart

@@ -18,6 +18,37 @@ import 'theme.dart';
 /// encloses the [ScrollView]. The [ScrollView.primary] flag is used to connect
 /// a [ScrollView] to the enclosing [PrimaryScrollController].
 ///
+/// {@tool dartpad --template=stateful_widget_cupertino}
+/// This example shows a [CupertinoPageScaffold] with a [ListView] as a [child].
+/// The [CupertinoButton] is connected to a callback that increments a counter.
+/// The [backgroundColor] can be changed.
+///
+/// ```dart
+/// int _count = 0;
+///
+/// Widget build(BuildContext context) {
+///   return CupertinoPageScaffold(
+///     // Uncomment to change the background color
+///     // backgroundColor: CupertinoColors.systemPink,
+///     navigationBar: CupertinoNavigationBar(
+///       middle: const Text('Sample Code'),
+///     ),
+///     child: ListView(
+///       children: [
+///         CupertinoButton(
+///           onPressed: () => setState(() => _count++),
+///           child: const Icon(CupertinoIcons.add),
+///         ),
+///         Center(
+///           child: Text('You have pressed the button $_count times.'),
+///         ),
+///       ],
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [CupertinoTabScaffold], a similar widget for tabbed applications.