Updated API doc references to obsolete Material button classes (#65665)

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

@@ -22,13 +22,25 @@ import 'theme_data.dart';
 /// Creates a button based on [Semantics], [Material], and [InkWell]
 /// widgets.
 ///
+/// ### This class is obsolete.
+///
+/// Custom button classes can be created by configuring the
+/// [ButtonStyle] of a [TextButton], [ElevatedButton] or an
+/// [OutlinedButton].
+///
+/// FlatButton, RaisedButton, and OutlineButton have been replaced by
+/// TextButton, ElevatedButton, and OutlinedButton respectively.
+/// ButtonTheme has been replaced by TextButtonTheme,
+/// ElevatedButtonTheme, and OutlinedButtonTheme. The original classes
+/// will be deprecated soon, please migrate code that uses them.
+/// There's a detailed migration guide for the new button and button
+/// theme classes in
+/// [flutter.dev/go/material-button-migration-guide](https://flutter.dev/go/material-button-migration-guide).
+///
 /// This class does not use the current [Theme] or [ButtonTheme] to
 /// compute default values for unspecified parameters. It's intended to
 /// be used for custom Material buttons that optionally incorporate defaults
 /// from the themes or from app-specific sources.
-///
-/// [RaisedButton] and [FlatButton] configure a [RawMaterialButton] based
-/// on the current [Theme] and [ButtonTheme].
 @Category(<String>['Material', 'Button'])
 class RawMaterialButton extends StatefulWidget {
   /// Create a button based on [Semantics], [Material], and [InkWell] widgets.

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

@@ -10,8 +10,6 @@ import 'package:flutter/rendering.dart';
 import 'button_bar_theme.dart';
 import 'button_theme.dart';
 import 'dialog.dart';
-import 'flat_button.dart';
-import 'raised_button.dart';
 
 /// An end-aligned row of buttons, laying out into a column if there is not
 /// enough horizontal space.
@@ -46,8 +44,9 @@ import 'raised_button.dart';
 ///
 /// See also:
 ///
-///  * [RaisedButton], a kind of button.
+///  * [TextButton], a simple flat button without a shadow.
-///  * [FlatButton], another kind of button.
+///  * [ElevatedButton], a filled button whose material elevates when pressed.
+///  * [OutlinedButton], a [TextButton] with a border outline.
 ///  * [Card], at the bottom of which it is common to place a [ButtonBar].
 ///  * [Dialog], which uses a [ButtonBar] for its actions.
 ///  * [ButtonBarTheme], which configures the [ButtonBar].
@@ -166,7 +165,7 @@ class ButtonBar extends StatelessWidget {
 
   /// The buttons to arrange horizontally.
   ///
-  /// Typically [RaisedButton] or [FlatButton] widgets.
+  /// Typically [ElevatedButton] or [TextButton] widgets.
   final List<Widget> children;
 
   @override

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

@@ -119,8 +119,7 @@ class _DefaultHeroTag {
 /// See also:
 ///
 ///  * [Scaffold], in which floating action buttons typically live.
-///  * [RaisedButton], another kind of button that appears to float above the
+///  * [ElevatedButton], a filled button whose material elevates when pressed.
-///    content.
 ///  * <https://material.io/design/components/buttons-floating-action-button.html>
 class FloatingActionButton extends StatelessWidget {
   /// Creates a circular floating action button.
@@ -358,7 +357,7 @@ class FloatingActionButton extends StatelessWidget {
   /// This controls the size of the shadow below the floating action button.
   ///
   /// Defaults to the same value as [elevation]. Setting this to zero makes the
-  /// floating action button work similar to a [RaisedButton] but the titular
+  /// floating action button work similar to an [ElevatedButton] but the titular
   /// "floating" effect is lost. The value is always non-negative.
   ///
   /// See also:

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

@@ -108,7 +108,7 @@ class PaginatedDataTable extends StatefulWidget {
   /// The table card's header.
   ///
   /// This is typically a [Text] widget, but can also be a [ButtonBar] with
-  /// [FlatButton]s. Suitable defaults are automatically provided for the font,
+  /// [TextButton]s. Suitable defaults are automatically provided for the font,
   /// button color, button padding, and so forth.
   ///
   /// If items in the table are selectable, then, when the selection is not

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

@@ -231,7 +231,7 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete
 ///                 title: const Text('Thanks!'),
 ///                 content: Text ('You typed "$value".'),
 ///                 actions: <Widget>[
-///                   FlatButton(
+///                   TextButton(
 ///                     onPressed: () { Navigator.pop(context); },
 ///                     child: const Text('OK'),
 ///                   ),

packages/flutter/lib/src/widgets/focus_traversal.dart

@@ -1278,9 +1278,8 @@ class _OrderedFocusInfo {
 ///   Widget build(BuildContext context) {
 ///     return FocusTraversalOrder(
 ///       order: NumericFocusOrder(order),
-///       child: FlatButton(
+///       child: TextButton(
 ///         autofocus: autofocus,
-///         focusColor: Colors.red,
 ///         onPressed: () => _handleOnPressed(),
 ///         child: Text(name),
 ///       ),