Updated the BottomNavigationBar API doc to link to NavigationBar (#12…

…5240)

The BottomNavigationBar API doc now makes it clear that NavigationBar is preferred in new M3 applications.

Fixes flutter/flutter#124687

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

@@ -63,6 +63,10 @@ enum BottomNavigationBarLandscapeLayout {
 /// A material widget that's displayed at the bottom of an app for selecting
 /// among a small number of views, typically between three and five.
 ///
+/// There is an updated version of this component, [NavigationBar], that's
+/// preferred for new applications and applications that are configured
+/// for Material 3 (see [ThemeData.useMaterial3]).
+///
 /// The bottom navigation bar consists of multiple items in the form of
 /// text labels, icons, or both, laid out on top of a piece of material. It
 /// provides quick navigation between the top-level views of an app. For larger
@@ -94,6 +98,18 @@ enum BottomNavigationBarLandscapeLayout {
 ///    case it's assumed that each item will have a different background color
 ///    and that background color will contrast well with white.
 ///
+/// ## Updating to [NavigationBar]
+///
+/// There is an updated version of this component, [NavigationBar],
+/// that's preferred for new applications and applications that are
+/// configured for Material 3 (see [ThemeData.useMaterial3]). The
+/// [NavigationBar] widget's visuals are a little bit different, see
+/// the Material 3 spec at
+/// <https://m3.material.io/components/navigation-bar/overview> for
+/// more details. The API is similar, destinations are defined with
+/// [NavigationDestination]s and [NavigationBar.onDestinationSelected]
+/// is called when a destination is tapped.
+///
 /// {@tool dartpad}
 /// This example shows a [BottomNavigationBar] as it is used within a [Scaffold]
 /// widget. The [BottomNavigationBar] has three [BottomNavigationBarItem]