diff --git a/packages/flutter/lib/src/widgets/will_pop_scope.dart b/packages/flutter/lib/src/widgets/will_pop_scope.dart
index 5a8be6d1ce..c1cf59c66d 100644
--- a/packages/flutter/lib/src/widgets/will_pop_scope.dart
+++ b/packages/flutter/lib/src/widgets/will_pop_scope.dart
@@ -9,10 +9,86 @@ import 'routes.dart';
 /// Registers a callback to veto attempts by the user to dismiss the enclosing
 /// [ModalRoute].
 ///
+/// {@tool snippet --template=stateful_widget}
+///
+/// Whenever the back button is pressed, you will get a callback at [onWillPop],
+/// which returns a [Future]. If the [Future] returns true, the screen is
+/// popped.
+///
+/// ```dart
+/// bool shouldPop = true;
+/// @override
+/// Widget build(BuildContext context) {
+///   return WillPopScope (
+///     onWillPop: () async {
+///       return shouldPop;
+///     },
+///     child: Text('WillPopScope sample'),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
+/// {@tool dartpad --template=stateful_widget_material}
+/// ```dart
+/// bool shouldPop = true;
+/// @override
+/// Widget build(BuildContext context) {
+///   return WillPopScope(
+///     onWillPop: () async {
+///       return shouldPop;
+///     },
+///     child: Scaffold(
+///       appBar: AppBar(
+///         title: Text("Flutter WillPopScope demo"),
+///       ),
+///       body: Center(
+///         child: Column(
+///           mainAxisAlignment: MainAxisAlignment.center,
+///           children: [
+///             OutlinedButton(
+///               child: Text('Push'),
+///               onPressed: () {
+///                 Navigator.of(context).push(
+///                   MaterialPageRoute(
+///                     builder: (context) {
+///                       return MyStatefulWidget();
+///                     },
+///                   ),
+///                 );
+///               },
+///             ),
+///             OutlinedButton(
+///               child: Text('shouldPop: $shouldPop'),
+///               onPressed: () {
+///                 setState(
+///                   () {
+///                     shouldPop = !shouldPop;
+///                   },
+///                 );
+///               },
+///             ),
+///             Text("Push to a new screen, then tap on shouldPop "
+///                 "button to toggle its value. Press the back "
+///                 "button in the appBar to check its behaviour "
+///                 "for different values of shouldPop"),
+///           ],
+///         ),
+///       ),
+///     ),
+///   );
+/// }
+/// ```
+///
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [ModalRoute.addScopedWillPopCallback] and [ModalRoute.removeScopedWillPopCallback],
 ///    which this widget uses to register and unregister [onWillPop].
+///  * [Form], which provides an `onWillPop` callback that enables the form
+///    to veto a `pop` initiated by the app's back button.
+///
 class WillPopScope extends StatefulWidget {
   /// Creates a widget that registers a callback to veto attempts by the user to
   /// dismiss the enclosing [ModalRoute].