Adding example for migrating to navigation drawer (#128295)

Fixes https://github.com/flutter/flutter/issues/127214

examples/api/lib/material/navigation_drawer/navigation_drawer.1.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+
+/// Flutter code sample for [NavigationDrawer].
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Flutter Demo',
+      debugShowCheckedModeBanner: false,
+      theme: ThemeData(
+        useMaterial3: true,
+      ),
+      home:  const MyHomePage(),
+    );
+  }
+}
+
+class MyHomePage extends StatelessWidget {
+  const MyHomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Drawer Demo'),
+      ),
+      drawer: NavigationDrawer(
+        children: <Widget>[
+          Padding(
+                padding: const EdgeInsets.fromLTRB(28, 16, 16, 10),
+                child: Text(
+                  'Drawer Header',
+                  style: Theme.of(context).textTheme.titleSmall,
+                ),
+              ),
+          const NavigationDrawerDestination(
+            icon: Icon(Icons.message),
+            label: Text('Messages'),
+          ),
+          const NavigationDrawerDestination(
+            icon: Icon(Icons.account_circle),
+            label: Text('Profile'),
+          ),
+          const NavigationDrawerDestination(
+            icon: Icon(Icons.settings),
+            label: Text('Settings'),
+          ),
+        ])
+    );
+  }
+}

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

@@ -130,6 +130,12 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 /// ```
 /// {@end-tool}
 ///
+/// {@tool snippet}
+/// This example shows how to migrate the above [Drawer] to a [NavigationDrawer].
+///
+/// See code in examples/api/lib/material/navigation_drawer/navigation_drawer.1.dart **
+/// {@end-tool}
+///
 /// An open drawer may be closed with a swipe to close gesture, pressing the
 /// escape key, by tapping the scrim, or by calling pop route function such as
 /// [Navigator.pop]. For example a drawer item might close the drawer when tapped: