Update origin material button API doc with obsolete API warnings (#64472)

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

@@ -52,6 +52,16 @@ enum ButtonBarLayoutBehavior {
 
 /// Used with [ButtonThemeData] to configure the color and geometry of buttons.
 ///
+/// ### This class is obsolete.
+///
+/// Please use one or more of the new buttons and their themes
+/// instead: [TextButton] and [TextButtonTheme], [ElevatedButton] and
+/// [ElevatedButtonTheme], [OutlinedButton] 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).
+///
 /// A button theme can be specified as part of the overall Material theme
 /// using [ThemeData.buttonTheme]. The Material theme's button theme data
 /// can be overridden with [ButtonTheme].
@@ -243,6 +253,23 @@ class ButtonTheme extends InheritedTheme {
 
 /// Used with [ButtonTheme] to configure the color and geometry of buttons.
 ///
+/// ### This class is obsolete.
+///
+/// Please use one or more of the new buttons and their themes instead:
+///
+///  * [TextButton], [TextButtonTheme], [TextButtonThemeData],
+///  * [ElevatedButton], [ElevatedButtonTheme], [ElevatedButtonThemeData],
+///  * [OutlinedButton], [OutlinedButtonTheme], [OutlinedButtonThemeData]
+///
+/// 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).
+///
 /// A button theme can be specified as part of the overall Material theme
 /// using [ThemeData.buttonTheme]. The Material theme's button theme data
 /// can be overridden with [ButtonTheme].

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

@@ -16,6 +16,17 @@ import 'theme_data.dart';
 
 /// A material design "flat button".
 ///
+/// ### This class is obsolete, please use [TextButton] instead.
+///
+/// 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).
+///
 /// A flat button is a text label displayed on a (zero elevation) [Material]
 /// widget that reacts to touches by filling with color.
 ///

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

@@ -21,6 +21,20 @@ import 'theme_data.dart';
 /// A utility class for building Material buttons that depend on the
 /// ambient [ButtonTheme] and [Theme].
 ///
+/// ### This class is obsolete.
+///
+/// FlatButton, RaisedButton, and OutlineButton have been replaced by
+/// TextButton, ElevatedButton, and OutlinedButton respectively.
+/// ButtonTheme has been replaced by TextButtonTheme,
+/// ElevatedButtonTheme, and OutlinedButtonTheme. The appearance of the
+/// new widgets can be customized by specifying a [ButtonStyle]
+/// or by creating a one-off style using a `styleFrom` method like
+/// [TextButton.styleFrom]. The original button 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).
+///
 /// The button's size will expand to fit the child widget, if necessary.
 ///
 /// MaterialButtons whose [onPressed] and [onLongPress] callbacks are null will be disabled. To have

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

@@ -26,6 +26,17 @@ const Duration _kElevationDuration = Duration(milliseconds: 75);
 
 /// Similar to a [FlatButton] with a thin grey rounded rectangle border.
 ///
+/// ### This class is obsolete, please use [OutlinedButton] instead.
+///
+/// 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).
+///
 /// The outline button's border shape is defined by [shape]
 /// and its appearance is defined by [borderSide], [disabledBorderColor],
 /// and [highlightedBorderColor]. By default the border is a one pixel

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

@@ -16,6 +16,17 @@ import 'theme_data.dart';
 
 /// A material design "raised button".
 ///
+/// ### This class is obsolete, please use [ElevatedButton] instead.
+///
+/// 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).
+///
 /// A raised button is based on a [Material] widget whose [Material.elevation]
 /// increases when the button is pressed.
 ///