Const constructor audit. (#76162)

dev/tools/gen_keycodes/data/keyboard_key.tmpl

@@ -20,7 +20,8 @@ import 'package:flutter/foundation.dart';
 ///  * [LogicalKeyboardKey], a class with static values that describe the keys
 ///    that are returned from [RawKeyEvent.logicalKey].
 abstract class KeyboardKey with Diagnosticable {
-  /// A const constructor so that subclasses may be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const KeyboardKey();
 }
 

packages/flutter/lib/src/animation/curves.dart

@@ -550,7 +550,7 @@ abstract class Curve2D extends ParametricCurve<Offset> {
 ///  * [Curve2D.generateSamples], which generates samples of this type.
 ///  * [Curve2D], a parametric curve that maps a double parameter to a 2D location.
 class Curve2DSample {
-  /// A const constructor for the sample so that subclasses can be const.
+  /// Creates an object that holds a sample; used with [Curve2D] subclasses.
   ///
   /// All arguments must not be null.
   const Curve2DSample(this.t, this.value) : assert(t != null), assert(value != null);

packages/flutter/lib/src/foundation/assertions.dart

@@ -93,7 +93,8 @@ class PartialStackFrame {
 /// A class that filters stack frames for additional filtering on
 /// [FlutterError.defaultStackFilter].
 abstract class StackFilter {
-  /// A const constructor to allow subclasses to be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const StackFilter();
 
   /// Filters the list of [StackFrame]s by updating corresponding indices in

packages/flutter/lib/src/foundation/key.dart

@@ -44,7 +44,8 @@ abstract class Key {
 ///
 ///  * [Widget.key], which discusses how widgets use keys.
 abstract class LocalKey extends Key {
-  /// Default constructor, used by subclasses.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const LocalKey() : super.empty();
 }
 

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

@@ -30,7 +30,6 @@ part of material_animated_icons;
 /// {@end-tool}
 ///
 class AnimatedIcon extends StatelessWidget {
-
   /// Creates an AnimatedIcon.
   ///
   /// The [progress] and [icon] arguments must not be null.

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

@@ -26,7 +26,8 @@ import 'theme_data.dart';
 ///  * [ElevatedButton], a filled ButtonStyleButton whose material elevates when pressed.
 ///  * [OutlinedButton], similar to [TextButton], but with an outline.
 abstract class ButtonStyleButton extends StatefulWidget {
-  /// Create a [ButtonStyleButton].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const ButtonStyleButton({
     Key? key,
     required this.onPressed,

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

@@ -153,6 +153,9 @@ abstract class InteractiveInkFeature extends InkFeature {
 ///  * [InkSplash.splashFactory]
 ///  * [InkRipple.splashFactory]
 abstract class InteractiveInkFeatureFactory {
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
+  ///
   /// Subclasses should provide a const constructor.
   const InteractiveInkFeatureFactory();
 

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

@@ -125,7 +125,8 @@ typedef MaterialPropertyResolver<T> = T Function(Set<MaterialState> states);
 /// ```
 /// {@end-tool}
 abstract class MaterialStateColor extends Color implements MaterialStateProperty<Color> {
-  /// Creates a [MaterialStateColor].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const MaterialStateColor(int defaultValue) : super(defaultValue);
 
   /// Creates a [MaterialStateColor] from a [MaterialPropertyResolver<Color>]
@@ -220,7 +221,8 @@ class _MaterialStateColor extends MaterialStateColor {
 ///  * [SystemMouseCursors], which defines cursors that are supported by
 ///    native platforms.
 abstract class MaterialStateMouseCursor extends MouseCursor implements MaterialStateProperty<MouseCursor> {
-  /// Creates a [MaterialStateMouseCursor].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const MaterialStateMouseCursor();
 
   @protected
@@ -333,7 +335,8 @@ class _EnabledAndDisabledMouseCursor extends MaterialStateMouseCursor {
 /// This class should only be used for parameters which are documented to take
 /// [MaterialStateBorderSide], otherwise only the default state will be used.
 abstract class MaterialStateBorderSide extends BorderSide implements MaterialStateProperty<BorderSide?> {
-  /// Creates a [MaterialStateBorderSide].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const MaterialStateBorderSide();
 
   /// Returns a [BorderSide] that's to be used when a Material component is
@@ -393,7 +396,8 @@ abstract class MaterialStateBorderSide extends BorderSide implements MaterialSta
 ///
 ///  * [ShapeBorder] the base class for shape outlines.
 abstract class MaterialStateOutlinedBorder extends OutlinedBorder implements MaterialStateProperty<OutlinedBorder?> {
-  /// Creates a [MaterialStateOutlinedBorder].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const MaterialStateOutlinedBorder();
 
   /// Returns an [OutlinedBorder] that's to be used when a Material component is

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

@@ -434,7 +434,7 @@ abstract class PageTransitionsBuilder {
 ///  * [CupertinoPageTransitionsBuilder], which defines a horizontal page
 ///    transition that matches native iOS page transitions.
 class FadeUpwardsPageTransitionsBuilder extends PageTransitionsBuilder {
-  /// Construct a [FadeUpwardsPageTransitionsBuilder].
+  /// Constructs a page transition animation that slides the page up.
   const FadeUpwardsPageTransitionsBuilder();
 
   @override
@@ -461,7 +461,8 @@ class FadeUpwardsPageTransitionsBuilder extends PageTransitionsBuilder {
 ///  * [CupertinoPageTransitionsBuilder], which defines a horizontal page
 ///    transition that matches native iOS page transitions.
 class OpenUpwardsPageTransitionsBuilder extends PageTransitionsBuilder {
-  /// Construct a [OpenUpwardsPageTransitionsBuilder].
+  /// Constructs a page transition animation that matches the transition used on
+  /// Android P.
   const OpenUpwardsPageTransitionsBuilder();
 
   @override
@@ -492,7 +493,8 @@ class OpenUpwardsPageTransitionsBuilder extends PageTransitionsBuilder {
 ///  * [CupertinoPageTransitionsBuilder], which defines a horizontal page
 ///    transition that matches native iOS page transitions.
 class ZoomPageTransitionsBuilder extends PageTransitionsBuilder {
-  /// Construct a [ZoomPageTransitionsBuilder].
+  /// Constructs a page transition animation that matches the transition used on
+  /// Android 10.
   const ZoomPageTransitionsBuilder();
 
   @override
@@ -522,7 +524,7 @@ class ZoomPageTransitionsBuilder extends PageTransitionsBuilder {
 ///  * [ZoomPageTransitionsBuilder], which defines a page transition similar
 ///    to the one provided in Android 10.
 class CupertinoPageTransitionsBuilder extends PageTransitionsBuilder {
-  /// Construct a [CupertinoPageTransitionsBuilder].
+  /// Constructs a page transition animation that matches the iOS transition.
   const CupertinoPageTransitionsBuilder();
 
   @override
@@ -558,12 +560,12 @@ class CupertinoPageTransitionsBuilder extends PageTransitionsBuilder {
 ///    transition that matches native iOS page transitions.
 @immutable
 class PageTransitionsTheme with Diagnosticable {
-  /// Construct a PageTransitionsTheme.
+  /// Constructs an object that selects a transition based on the platform.
   ///
   /// By default the list of builders is: [FadeUpwardsPageTransitionsBuilder]
   /// for [TargetPlatform.android], and [CupertinoPageTransitionsBuilder] for
   /// [TargetPlatform.iOS] and [TargetPlatform.macOS].
-  const PageTransitionsTheme({ Map<TargetPlatform, PageTransitionsBuilder>? builders }) : _builders = builders;
+  const PageTransitionsTheme({ Map<TargetPlatform, PageTransitionsBuilder> builders = _defaultBuilders }) : _builders = builders;
 
   static const Map<TargetPlatform, PageTransitionsBuilder> _defaultBuilders = <TargetPlatform, PageTransitionsBuilder>{
     TargetPlatform.android: FadeUpwardsPageTransitionsBuilder(),
@@ -574,8 +576,8 @@ class PageTransitionsTheme with Diagnosticable {
   };
 
   /// The [PageTransitionsBuilder]s supported by this theme.
-  Map<TargetPlatform, PageTransitionsBuilder> get builders => _builders ?? _defaultBuilders;
-  final Map<TargetPlatform, PageTransitionsBuilder>? _builders;
+  Map<TargetPlatform, PageTransitionsBuilder> get builders => _builders;
+  final Map<TargetPlatform, PageTransitionsBuilder> _builders;
 
   /// Delegates to the builder for the current [ThemeData.platform]
   /// or [FadeUpwardsPageTransitionsBuilder].

packages/flutter/lib/src/painting/gradient.dart

@@ -68,7 +68,8 @@ _ColorsAndStops _interpolateColorsAndStops(
 /// a [GradientRotation] of `pi/4` radians (i.e. 45 degrees).
 @immutable
 abstract class GradientTransform {
-  /// A const constructor so that subclasses may be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const GradientTransform();
 
   /// When a [Gradient] creates its [Shader], it will call this method to

packages/flutter/lib/src/rendering/custom_paint.dart

@@ -287,7 +287,6 @@ abstract class CustomPainter extends Listenable {
 ///  * [CustomPainter], which creates instances of this class.
 @immutable
 class CustomPainterSemantics {
-
   /// Creates semantics information describing a rectangle on a canvas.
   ///
   /// Arguments `rect` and `properties` must not be null.

packages/flutter/lib/src/rendering/viewport.dart

@@ -99,7 +99,6 @@ abstract class RenderAbstractViewport extends RenderObject {
 /// the [rect] position said element would have in the viewport at that
 /// [offset].
 class RevealedOffset {
-
   /// Instantiates a return value for [RenderAbstractViewport.getOffsetToReveal].
   const RevealedOffset({
     required this.offset,

packages/flutter/lib/src/semantics/semantics_event.dart

@@ -95,7 +95,6 @@ class AnnounceSemanticsEvent extends SemanticsEvent {
 ///
 /// This is only used by Android to announce tooltip values.
 class TooltipSemanticsEvent extends SemanticsEvent {
-
   /// Constructs an event that triggers a tooltip announcement by the platform.
   const TooltipSemanticsEvent(this.message) : super('tooltip');
 
@@ -115,7 +114,6 @@ class TooltipSemanticsEvent extends SemanticsEvent {
 /// Currently only honored on Android. Triggers a long-press specific sound
 /// when TalkBack is enabled.
 class LongPressSemanticsEvent extends SemanticsEvent {
-
   /// Constructs an event that triggers a long-press semantic feedback by the platform.
   const LongPressSemanticsEvent() : super('longPress');
 
@@ -128,7 +126,6 @@ class LongPressSemanticsEvent extends SemanticsEvent {
 /// Currently only honored on Android. Triggers a tap specific sound when
 /// TalkBack is enabled.
 class TapSemanticEvent extends SemanticsEvent {
-
   /// Constructs an event that triggers a long-press semantic feedback by the platform.
   const TapSemanticEvent() : super('tap');
 

packages/flutter/lib/src/services/binary_messenger.dart

@@ -15,7 +15,8 @@ typedef MessageHandler = Future<ByteData?>? Function(ByteData? message);
 ///
 /// This class also registers handlers for incoming messages.
 abstract class BinaryMessenger {
-  /// A const constructor to allow subclasses to be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const BinaryMessenger();
 
   /// Calls the handler registered for the given channel.

packages/flutter/lib/src/services/keyboard_key.dart

@@ -20,7 +20,8 @@ import 'package:flutter/foundation.dart';
 ///  * [LogicalKeyboardKey], a class with static values that describe the keys
 ///    that are returned from [RawKeyEvent.logicalKey].
 abstract class KeyboardKey with Diagnosticable {
-  /// A const constructor so that subclasses may be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const KeyboardKey();
 }
 

packages/flutter/lib/src/services/platform_views.dart

@@ -223,7 +223,7 @@ class PlatformViewsService {
 ///
 /// A Dart version of Android's [MotionEvent.PointerProperties](https://developer.android.com/reference/android/view/MotionEvent.PointerProperties).
 class AndroidPointerProperties {
-  /// Creates an AndroidPointerProperties.
+  /// Creates an [AndroidPointerProperties] object.
   ///
   /// All parameters must not be null.
   const AndroidPointerProperties({

packages/flutter/lib/src/services/raw_keyboard.dart

@@ -114,10 +114,8 @@ enum ModifierKey {
 ///  * [RawKeyboard], which uses these interfaces to expose key data.
 @immutable
 abstract class RawKeyEventData {
-  /// Abstract const constructor.
-  ///
-  /// This constructor enables subclasses to provide const constructors so that
-  /// they can be used in const expressions.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const RawKeyEventData();
 
   /// Returns true if the given [ModifierKey] was pressed at the time of this
@@ -255,8 +253,8 @@ abstract class RawKeyEventData {
 ///  * [RawKeyboardListener], a widget that listens for raw key events.
 @immutable
 abstract class RawKeyEvent with Diagnosticable {
-  /// Initializes fields for subclasses, and provides a const constructor for
-  /// const subclasses.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const RawKeyEvent({
     required this.data,
     this.character,

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

@@ -42,7 +42,8 @@ BuildContext _getParent(BuildContext context) {
 ///    [BuildContext].
 @immutable
 abstract class Intent with Diagnosticable {
-  /// A const constructor for an [Intent].
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const Intent();
 
   /// An intent that is mapped to a [DoNothingAction], which, as the name
@@ -485,7 +486,7 @@ class CallbackAction<T extends Intent> extends Action<T> {
 ///  - [Actions] widget, which defines a mapping between a in [Intent] type and
 ///    an [Action].
 class ActionDispatcher with Diagnosticable {
-  /// Const constructor so that subclasses can be immutable.
+  /// Creates an action dispatcher that invokes actions directly.
   const ActionDispatcher();
 
   /// Invokes the given `action`, passing it the given `intent`.
@@ -1561,7 +1562,7 @@ class DoNothingAction extends Action<Intent> {
 ///  * [WidgetsApp.shortcuts], which defines the shortcuts to use in an
 ///    application (and defaults to [WidgetsApp.defaultShortcuts]).
 class ActivateIntent extends Intent {
-  /// Creates a const [ActivateIntent] so subclasses can be const.
+  /// Creates an intent that activates the currently focused control.
   const ActivateIntent();
 }
 
@@ -1578,7 +1579,7 @@ class ActivateIntent extends Intent {
 ///  * [WidgetsApp.shortcuts], which defines the shortcuts to use in an
 ///    application (and defaults to [WidgetsApp.defaultShortcuts]).
 class ButtonActivateIntent extends Intent {
-  /// Creates a const [ButtonActivateIntent] so subclasses can be const.
+  /// Creates an intent that the currently focused control, if it's a button.
   const ButtonActivateIntent();
 }
 
@@ -1608,7 +1609,7 @@ abstract class SelectAction extends Action<SelectIntent> {}
 ///  - [ModalRoute] which listens for this intent to dismiss modal routes
 ///    (dialogs, pop-up menus, drawers, etc).
 class DismissIntent extends Intent {
-  /// Creates a const [DismissIntent].
+  /// Creates an intent that dismisses the currently focused widget.
   const DismissIntent();
 }
 
@@ -1619,8 +1620,11 @@ abstract class DismissAction extends Action<DismissIntent> {}
 
 /// An [Intent] that evaluates a series of specified [orderedIntents] for
 /// execution.
+///
+/// The first intent that matches an enabled action is used.
 class PrioritizedIntents extends Intent {
-  /// Creates a set of const [PrioritizedIntents].
+  /// Creates an intent that is used with [PrioritizedAction] to specify a list
+  /// of intents, the first available of which will be used.
   const PrioritizedIntents({
     required this.orderedIntents,
   })  : assert(orderedIntents != null);

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

@@ -113,7 +113,8 @@ enum TraversalDirection {
 ///    focus traversal in a direction.
 @immutable
 abstract class FocusTraversalPolicy with Diagnosticable {
-  /// A const constructor so subclasses can be const.
+  /// Abstract const constructor. This constructor enables subclasses to provide
+  /// const constructors so that they can be used in const expressions.
   const FocusTraversalPolicy();
 
   /// Returns the node that should receive focus if focus is traversing
@@ -1190,8 +1191,7 @@ abstract class FocusOrder with Diagnosticable implements Comparable<FocusOrder>
 ///  * [FocusTraversalOrder], a widget that assigns an order to a widget subtree
 ///    for the [OrderedTraversalPolicy] to use.
 class NumericFocusOrder extends FocusOrder {
-  /// Const constructor. This constructor enables subclasses to provide
-  /// const constructors so that they can be used in const expressions.
+  /// Creates an object that describes a focus traversal order numerically.
   const NumericFocusOrder(this.order) : assert(order != null);
 
   /// The numerical order to assign to the widget subtree using
@@ -1219,7 +1219,7 @@ class NumericFocusOrder extends FocusOrder {
 /// traversed with the keyboard.
 ///
 /// This sorts strings using Dart's default string comparison, which is not
-/// locale specific.
+/// locale-specific.
 ///
 /// {@macro flutter.widgets.FocusOrder.comparable}
 ///
@@ -1228,8 +1228,7 @@ class NumericFocusOrder extends FocusOrder {
 ///  * [FocusTraversalOrder], a widget that assigns an order to a widget subtree
 ///    for the [OrderedTraversalPolicy] to use.
 class LexicalFocusOrder extends FocusOrder {
-  /// Const constructor. This constructor enables subclasses to provide
-  /// const constructors so that they can be used in const expressions.
+  /// Creates an object that describes a focus traversal order lexically.
   const LexicalFocusOrder(this.order) : assert(order != null);
 
   /// The String that defines the lexical order to assign to the widget subtree
@@ -1406,7 +1405,8 @@ class OrderedTraversalPolicy extends FocusTraversalPolicy with DirectionalFocusT
 /// The order for a widget is determined by the [FocusOrder] returned by
 /// [FocusTraversalOrder.of] for a particular context.
 class FocusTraversalOrder extends InheritedWidget {
-  /// A const constructor so that subclasses can be const.
+  /// Creates an inherited widget used to describe the focus order of
+  /// the [child] subtree.
   const FocusTraversalOrder({Key? key, required this.order, required Widget child}) : super(key: key, child: child);
 
   /// The order for the widget descendants of this [FocusTraversalOrder].
@@ -1819,8 +1819,9 @@ class _FocusTraversalGroupMarker extends InheritedWidget {
 /// An intent for use with the [RequestFocusAction], which supplies the
 /// [FocusNode] that should be focused.
 class RequestFocusIntent extends Intent {
-  /// A const constructor for a [RequestFocusIntent], so that subclasses may be
-  /// const.
+  /// Creates an intent used with [RequestFocusAction].
+  ///
+  /// The argument must not be null.
   const RequestFocusIntent(this.focusNode)
       : assert(focusNode != null);
 
@@ -1864,7 +1865,7 @@ class RequestFocusAction extends Action<RequestFocusIntent> {
 ///
 /// See [FocusTraversalPolicy] for more information about focus traversal.
 class NextFocusIntent extends Intent {
-  /// Creates a const [NextFocusIntent] so subclasses can be const.
+  /// Creates an intent that is used with [NextFocusAction].
   const NextFocusIntent();
 }
 
@@ -1887,7 +1888,7 @@ class NextFocusAction extends Action<NextFocusIntent> {
 ///
 /// See [FocusTraversalPolicy] for more information about focus traversal.
 class PreviousFocusIntent extends Intent {
-  /// Creates a const [PreviousFocusIntent] so subclasses can be const.
+  /// Creates an intent that is used with [PreviousFocusAction].
   const PreviousFocusIntent();
 }
 
@@ -1916,8 +1917,7 @@ class PreviousFocusAction extends Action<PreviousFocusIntent> {
 ///
 /// See [FocusTraversalPolicy] for more information about focus traversal.
 class DirectionalFocusIntent extends Intent {
-  /// Creates a [DirectionalFocusIntent] intending to move the focus in the
-  /// given [direction].
+  /// Creates an intent used to move the focus in the given [direction].
   const DirectionalFocusIntent(this.direction, {this.ignoreTextFields = true})
       : assert(ignoreTextFields != null);
 

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

@@ -16,6 +16,10 @@ import 'framework.dart';
 /// [Scaffold] sets its app bar height to the app bar's preferred height
 /// plus the height of the system status bar.
 ///
+/// Widgets that need to know the preferred size of their child can require
+/// that their child implement this interface by using this class rather
+/// than [Widget] as the type of their `child` property.
+///
 /// Use [PreferredSize] to give a preferred size to an arbitrary widget.
 abstract class PreferredSizeWidget implements Widget {
   /// The size this widget would prefer if it were otherwise unconstrained.
@@ -33,7 +37,13 @@ abstract class PreferredSizeWidget implements Widget {
 /// affect the child's layout in any way. It just advertises a preferred size
 /// which can be used by the parent.
 ///
-/// Widgets like [AppBar] implement a [PreferredSizeWidget].
+/// Parents like [Scaffold] use [PreferredSizeWidget] to require that their
+/// children implement that interface. To give a preferred size to an arbitrary
+/// widget so that it can be used in a `child` property of that type, this
+/// widget, [PreferredSize], can be used.
+///
+/// Widgets like [AppBar] implement a [PreferredSizeWidget], so that this
+/// [PreferredSize] widget is not necessary for them.
 ///
 /// {@tool dartpad --template=stateless_widget_material}
 ///
@@ -111,7 +121,7 @@ abstract class PreferredSizeWidget implements Widget {
 ///    its preferred size.
 ///  * [AppBar] and [TabBar], which implement PreferredSizeWidget.
 class PreferredSize extends StatelessWidget implements PreferredSizeWidget {
-  /// Creates a widget that has a preferred size.
+  /// Creates a widget that has a preferred size that the parent can query.
   const PreferredSize({
     Key? key,
     required this.child,