Clarify ButtonThemeData usage and documentation #98691

Feedback from @rydmike in #98537 (comment)

ButtonThemeData

The ButtonThemeData class is marked as obsolete in the docs, but not as deprecated.

In its theme ButtonTheme:

And in its theme data ButtonThemeData:

In addition to the buttons that will be removed [FlatButton, OutlineButton, RaisedButton], the theme and theme data is used by the buttons' parent class MaterialButton and the ButtonBar and its theme ButtonBarTheme, plus as far I could notice DropdownButton uses one property from it as well.

Instead of having the docs above mention that it is used by buttons that will no longer exist, maybe consider updating the doc comment and instead mention the usage by ButtonBar, DropdownButton and MaterialButton, if it will remain. It kind of will have to, but more on that below.

Perhaps for the update also consider updating the doc comment for the buttonTheme property in ThemeData to better reflects its remaining usage in ButtonBar, DropdownButton and MaterialButton

Some of these doc updates will be completed in the course of resolving #98537

In general, I think the current use case is unclear to users, obsolete is not deprecated, but it's not really obsolete either if other parts of the framework still use ButtonThemeData. There is definitely some opportunity for better clarity and guidance here - even if that is just to say we plan to make more changes in the future that will eventually remove this class.

cc @HansMuller @darrenaustin