Updated the Drawer API doc to link to NavigationDrawer (flutter#1…

…26915)

fixes flutter#124887

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

@@ -53,6 +53,10 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 /// A Material Design panel that slides in horizontally from the edge of a
 /// [Scaffold] to show navigation links in an application.
 ///
+/// There is a Material 3 version of this component, [NavigationDrawer],
+/// that's preferred for applications that are configured for Material 3
+/// (see [ThemeData.useMaterial3]).
+///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=WRj86iHihgY}
 ///
 /// Drawers are typically used with the [Scaffold.drawer] property. The child of
@@ -67,6 +71,18 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 ///
 /// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/drawer.mp4}
 ///
+/// ## Updating to [NavigationDrawer]
+///
+/// There is a Material 3 version of this component, [NavigationDrawer],
+/// that's preferred for applications that are configured for Material 3
+/// (see [ThemeData.useMaterial3]). The [NavigationDrawer] widget's visual
+/// are a little bit different, see the Material 3 spec at
+/// <https://m3.material.io/components/navigation-drawer/overview> for
+/// more details. While the [Drawer] widget can have only one child, the
+/// [NavigationDrawer] widget can have list of widgets, which typically contains
+/// [NavigationDrawerDestination] widgets and/or customized widgets like headlines
+/// and dividers.
+///
 /// {@tool snippet}
 /// This example shows how to create a [Scaffold] that contains an [AppBar] and
 /// a [Drawer]. A user taps the "menu" icon in the [AppBar] to open the