From b61dec79c753c68339cc6d9e6cf7e39fa685ee35 Mon Sep 17 00:00:00 2001 From: Dan Field Date: Tue, 3 Dec 2019 13:59:19 -0800 Subject: [PATCH] Start fixing docs (#45977) --- .../src/animation/animation_controller.dart | 11 ++- packages/flutter/lib/src/animation/tween.dart | 4 +- .../flutter/lib/src/cupertino/colors.dart | 36 +++---- .../lib/src/cupertino/icon_theme_data.dart | 2 +- .../flutter/lib/src/cupertino/picker.dart | 2 +- packages/flutter/lib/src/cupertino/route.dart | 4 +- .../lib/src/cupertino/tab_scaffold.dart | 4 +- .../flutter/lib/src/cupertino/text_field.dart | 8 +- .../lib/src/foundation/assertions.dart | 9 +- .../lib/src/foundation/diagnostics.dart | 9 +- .../flutter/lib/src/foundation/isolates.dart | 2 +- .../flutter/lib/src/foundation/licenses.dart | 2 +- .../flutter/lib/src/foundation/platform.dart | 2 +- packages/flutter/lib/src/gestures/events.dart | 7 +- .../flutter/lib/src/gestures/force_press.dart | 5 +- .../flutter/lib/src/gestures/hit_test.dart | 6 +- .../lib/src/gestures/mouse_tracking.dart | 2 +- .../flutter/lib/src/gestures/multitap.dart | 4 +- packages/flutter/lib/src/gestures/tap.dart | 6 +- packages/flutter/lib/src/gestures/team.dart | 2 +- .../lib/src/material/bottom_app_bar.dart | 4 +- .../flutter/lib/src/material/button_bar.dart | 2 +- .../flutter/lib/src/material/chip_theme.dart | 2 +- .../lib/src/material/dialog_theme.dart | 4 +- .../lib/src/material/divider_theme.dart | 6 +- packages/flutter/lib/src/material/icons.dart | 2 +- .../src/material/material_localizations.dart | 4 +- .../src/material/page_transitions_theme.dart | 2 +- .../lib/src/material/selectable_text.dart | 2 +- .../flutter/lib/src/material/text_field.dart | 4 +- .../flutter/lib/src/material/typography.dart | 2 +- .../flutter/lib/src/rendering/object.dart | 4 +- .../flutter/lib/src/rendering/proxy_box.dart | 26 ++--- .../flutter/lib/src/scheduler/binding.dart | 3 +- .../flutter/lib/src/semantics/semantics.dart | 6 +- packages/flutter/lib/src/widgets/app.dart | 96 +++++++++---------- packages/flutter/lib/src/widgets/basic.dart | 4 +- .../lib/src/widgets/editable_text.dart | 2 +- .../lib/src/widgets/widget_inspector.dart | 6 +- 39 files changed, 150 insertions(+), 158 deletions(-) diff --git a/packages/flutter/lib/src/animation/animation_controller.dart b/packages/flutter/lib/src/animation/animation_controller.dart index 5c645aa22e0..f27dea93a06 100644 --- a/packages/flutter/lib/src/animation/animation_controller.dart +++ b/packages/flutter/lib/src/animation/animation_controller.dart @@ -125,12 +125,13 @@ enum AnimationBehavior { /// /// {@tool sample} /// -/// Here is a stateful [Foo] widget. Its [State] uses the +/// Here is a stateful `Foo` widget. Its [State] uses the /// [SingleTickerProviderStateMixin] to implement the necessary -/// [TickerProvider], creating its controller in the [initState] method and -/// disposing of it in the [dispose] method. The duration of the controller is -/// configured from a property in the [Foo] widget; as that changes, the -/// [didUpdateWidget] method is used to update the controller. +/// [TickerProvider], creating its controller in the [State.initState] method +/// and disposing of it in the [State.dispose] method. The duration of the +/// controller is configured from a property in the `Foo` widget; as that +/// changes, the [State.didUpdateWidget] method is used to update the +/// controller. /// /// ```dart /// class Foo extends StatefulWidget { diff --git a/packages/flutter/lib/src/animation/tween.dart b/packages/flutter/lib/src/animation/tween.dart index 5d04773d51b..4be58be11dc 100644 --- a/packages/flutter/lib/src/animation/tween.dart +++ b/packages/flutter/lib/src/animation/tween.dart @@ -396,12 +396,12 @@ class ConstantTween extends Tween { /// Create a tween whose [begin] and [end] values equal [value]. ConstantTween(T value) : super(begin: value, end: value); - /// This tween doesn't interpolate, it always returns [value]. + /// This tween doesn't interpolate, it always returns the same value. @override T lerp(double t) => begin; @override - String toString() => '$runtimeType(value: begin)'; + String toString() => '$runtimeType(value: $begin)'; } /// Transforms the value of the given animation by the given curve. diff --git a/packages/flutter/lib/src/cupertino/colors.dart b/packages/flutter/lib/src/cupertino/colors.dart index 8d5898f0809..bd8cb5208aa 100644 --- a/packages/flutter/lib/src/cupertino/colors.dart +++ b/packages/flutter/lib/src/cupertino/colors.dart @@ -2,7 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'dart:ui' show Color; +import 'dart:ui' show Color, Brightness; import '../../foundation.dart'; import '../widgets/basic.dart'; @@ -790,8 +790,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.light], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.light]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.light], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.light]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `false`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.base]. final Color color; @@ -801,8 +801,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.dark], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.dark]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.dark], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.dark]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `false`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.base]. final Color darkColor; @@ -812,8 +812,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.light], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.light]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.light], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.light]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `true`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.base]. final Color highContrastColor; @@ -823,8 +823,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.dark], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.dark]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.dark], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.dark]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `true`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.base]. final Color darkHighContrastColor; @@ -834,8 +834,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.light], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.light]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.light], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.light]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `false`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.elevated]. final Color elevatedColor; @@ -845,8 +845,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.dark], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.dark]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.dark], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.dark]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `false`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.elevated]. final Color darkElevatedColor; @@ -856,8 +856,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.light], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.light]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.light], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.light]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `true`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.elevated]. final Color highContrastElevatedColor; @@ -867,8 +867,8 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// In other words, this color will be the effective color of the [CupertinoDynamicColor] /// after it is resolved against a [BuildContext] that: - /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.dark], - /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.dark]. + /// - has a [CupertinoTheme] whose [brightness] is [Brightness.dark], + /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [Brightness.dark]. /// - has a [MediaQuery] whose [MediaQueryData.highContrast] is `true`. /// - has a [CupertinoUserInterfaceLevel] that indicates [CupertinoUserInterfaceLevelData.elevated]. final Color darkHighContrastElevatedColor; @@ -920,7 +920,7 @@ class CupertinoDynamicColor extends Color with DiagnosticableMixin implements Di /// /// For example, if the given [BuildContext] indicates the widgets in the subtree /// should be displayed in dark mode (the surrounding [CupertinoTheme]'s [CupertinoThemeData.brightness] - /// or [MediaQuery]'s [MediaQueryData.platformBrightness] is [PlatformBrightness.dark]), + /// or [MediaQuery]'s [MediaQueryData.platformBrightness] is [Brightness.dark]), /// with a high accessibility contrast (the surrounding [MediaQuery]'s [MediaQueryData.highContrast] /// is `true`), and an elevated interface elevation (the surrounding [CupertinoUserInterfaceLevel]'s /// `data` is [CupertinoUserInterfaceLevelData.elevated]), the resolved diff --git a/packages/flutter/lib/src/cupertino/icon_theme_data.dart b/packages/flutter/lib/src/cupertino/icon_theme_data.dart index 9b87e284d3b..2769fbd4f0b 100644 --- a/packages/flutter/lib/src/cupertino/icon_theme_data.dart +++ b/packages/flutter/lib/src/cupertino/icon_theme_data.dart @@ -19,7 +19,7 @@ class CupertinoIconThemeData extends IconThemeData with DiagnosticableMixin { double size }) : super(color: color, opacity: opacity, size: size); - /// Called by [IconThemeData.of] to resolve [color] against the given [BuildContext]. + /// Called by [IconTheme.of] to resolve [color] against the given [BuildContext]. @override IconThemeData resolve(BuildContext context) { final Color resolvedColor = CupertinoDynamicColor.resolve(color, context); diff --git a/packages/flutter/lib/src/cupertino/picker.dart b/packages/flutter/lib/src/cupertino/picker.dart index 5a3f4fae2f6..26b220a4cac 100644 --- a/packages/flutter/lib/src/cupertino/picker.dart +++ b/packages/flutter/lib/src/cupertino/picker.dart @@ -26,7 +26,7 @@ const double _kForegroundScreenOpacityFraction = 0.7; /// Displays its children widgets on a wheel for selection and /// calls back when the currently selected item changes. /// -/// By default, the first child in [children] will be the initially selected child. +/// By default, the first child in `children` will be the initially selected child. /// The index of a different child can be specified in [scrollController], to make /// that child the initially selected child. /// diff --git a/packages/flutter/lib/src/cupertino/route.dart b/packages/flutter/lib/src/cupertino/route.dart index 6b91cfa2463..bc5bfe07dc9 100644 --- a/packages/flutter/lib/src/cupertino/route.dart +++ b/packages/flutter/lib/src/cupertino/route.dart @@ -883,8 +883,8 @@ class _CupertinoModalPopupRoute extends PopupRoute { /// /// See also: /// -/// * [ActionSheet], which is the widget usually returned by the `builder` -/// argument to [showCupertinoModalPopup]. +/// * [CupertinoActionSheet], which is the widget usually returned by the +/// `builder` argument to [showCupertinoModalPopup]. /// * Future showCupertinoModalPopup({ @required BuildContext context, diff --git a/packages/flutter/lib/src/cupertino/tab_scaffold.dart b/packages/flutter/lib/src/cupertino/tab_scaffold.dart index 6ebeb806c02..1a59a4f997f 100644 --- a/packages/flutter/lib/src/cupertino/tab_scaffold.dart +++ b/packages/flutter/lib/src/cupertino/tab_scaffold.dart @@ -119,7 +119,7 @@ class CupertinoTabController extends ChangeNotifier { /// /// Tabs' contents are built with the provided [tabBuilder] at the active /// tab index. The [tabBuilder] must be able to build the same number of -/// pages as there are [tabBar.items]. Inactive tabs will be moved [Offstage] +/// pages as there are [tabBar] items. Inactive tabs will be moved [Offstage] /// and their animations disabled. /// /// Adding/removing tabs, or changing the order of tabs is supported but not @@ -280,7 +280,7 @@ class CupertinoTabScaffold extends StatefulWidget { /// By default uses [CupertinoTheme]'s `scaffoldBackgroundColor` when null. final Color backgroundColor; - /// Whether the [child] should size itself to avoid the window's bottom inset. + /// Whether the body should size itself to avoid the window's bottom inset. /// /// For example, if there is an onscreen keyboard displayed above the /// scaffold, the body can be resized to avoid overlapping the keyboard, which diff --git a/packages/flutter/lib/src/cupertino/text_field.dart b/packages/flutter/lib/src/cupertino/text_field.dart index a02a8454902..b3c3631ac60 100644 --- a/packages/flutter/lib/src/cupertino/text_field.dart +++ b/packages/flutter/lib/src/cupertino/text_field.dart @@ -165,8 +165,8 @@ class _CupertinoTextFieldSelectionGestureDetectorBuilder extends TextSelectionGe /// rounded rectangle border around the text field. If you set the [decoration] /// property to null, the decoration will be removed entirely. /// -/// Remember to [dispose] of the [TextEditingController] when it is no longer needed. -/// This will ensure we discard any resources used by the object. +/// Remember to call [TextEditingController.dispose] when it is no longer +/// needed. This will ensure we discard any resources used by the object. /// /// See also: /// @@ -400,7 +400,7 @@ class CupertinoTextField extends StatefulWidget { /// paste and cut will be disabled regardless. final ToolbarOptions toolbarOptions; - /// {@macro flutter.material.inputDecorator.textAlignVertical} + /// {@macro flutter.widgets.inputDecorator.textAlignVertical} final TextAlignVertical textAlignVertical; /// {@macro flutter.widgets.editableText.readOnly} @@ -539,7 +539,7 @@ class CupertinoTextField extends StatefulWidget { /// {@macro flutter.widgets.editableText.scrollController} final ScrollController scrollController; - /// {@macro flutter.widgets.edtiableText.scrollPhysics} + /// {@macro flutter.widgets.editableText.scrollPhysics} final ScrollPhysics scrollPhysics; /// {@macro flutter.rendering.editable.selectionEnabled} diff --git a/packages/flutter/lib/src/foundation/assertions.dart b/packages/flutter/lib/src/foundation/assertions.dart index d342f73adc2..fa4ce003a37 100644 --- a/packages/flutter/lib/src/foundation/assertions.dart +++ b/packages/flutter/lib/src/foundation/assertions.dart @@ -182,7 +182,7 @@ class ErrorHint extends _ErrorDiagnostic { /// An [ErrorSpacer] creates an empty [DiagnosticsNode], that can be used to /// tune the spacing between other [DiagnosticsNode] objects. class ErrorSpacer extends DiagnosticsProperty { - /// Creates an empty space to insert into a list of [DiagnosticNode] objects + /// Creates an empty space to insert into a list of [DiagnosticsNode] objects /// typically within a [FlutterError] object. ErrorSpacer() : super( '', @@ -516,7 +516,7 @@ class FlutterError extends Error with DiagnosticableTreeMixin implements Asserti /// Create an error message from a list of [DiagnosticsNode]s. /// - /// By convention, there should be exactly one [FlutterSummary] in the list, + /// By convention, there should be exactly one [ErrorSummary] in the list, /// and it should be the first entry. /// /// Other entries are typically [ErrorDescription]s (for material that is @@ -774,11 +774,6 @@ void debugPrintStack({StackTrace stackTrace, String label, int maxFrames}) { /// Diagnostic with a [StackTrace] [value] suitable for displaying stack traces /// as part of a [FlutterError] object. -/// -/// See also: -/// -/// * [FlutterErrorBuilder.addStackTrace], which is the typical way [StackTrace] -/// objects are added to a [FlutterError]. class DiagnosticsStackTrace extends DiagnosticsBlock { /// Creates a diagnostic for a stack trace. /// diff --git a/packages/flutter/lib/src/foundation/diagnostics.dart b/packages/flutter/lib/src/foundation/diagnostics.dart index fef3bdc7028..accdff9c253 100644 --- a/packages/flutter/lib/src/foundation/diagnostics.dart +++ b/packages/flutter/lib/src/foundation/diagnostics.dart @@ -166,8 +166,8 @@ enum DiagnosticsTreeStyle { /// /// See also: /// - /// * [DebugOverflowIndicator], which uses this style to display just the - /// immediate children of a node. + /// * [DebugOverflowIndicatorMixin], which uses this style to display just + /// the immediate children of a node. shallow, /// Render only the children of a node truncating before the tree becomes too @@ -326,9 +326,6 @@ class TextTreeConfiguration { /// Mandatory string to add after the properties of a node regardless of /// whether the node has any properties. - /// - /// See [headerLineTextConfiguration] for an example of using this field to - /// add a colon at the end of the header line. final String mandatoryAfterProperties; /// Property separator to add between properties. @@ -1061,7 +1058,7 @@ bool _isSingleLine(DiagnosticsTreeStyle style) { /// /// See also: /// -/// * [DiagnosticsNode.toStringDeep], which uses a [TextRender] to return a +/// * [DiagnosticsNode.toStringDeep], which uses a [TextTreeRenderer] to return a /// string representation of this node and its descendants. class TextTreeRenderer { /// Creates a [TextTreeRenderer] object with the given arguments specifying diff --git a/packages/flutter/lib/src/foundation/isolates.dart b/packages/flutter/lib/src/foundation/isolates.dart index 6982a3bf6df..8fb0808f53f 100644 --- a/packages/flutter/lib/src/foundation/isolates.dart +++ b/packages/flutter/lib/src/foundation/isolates.dart @@ -25,7 +25,7 @@ typedef _ComputeImpl = Future Function(ComputeCallback callback, /// /// This is useful for operations that take longer than a few milliseconds, and /// which would therefore risk skipping frames. For tasks that will only take a -/// few milliseconds, consider [scheduleTask] instead. +/// few milliseconds, consider [SchedulerBinding.scheduleTask] instead. /// /// {@template flutter.foundation.compute.types} /// `Q` is the type of the message that kicks off the computation. diff --git a/packages/flutter/lib/src/foundation/licenses.dart b/packages/flutter/lib/src/foundation/licenses.dart index 03a51206e41..fcda6ac42b9 100644 --- a/packages/flutter/lib/src/foundation/licenses.dart +++ b/packages/flutter/lib/src/foundation/licenses.dart @@ -115,7 +115,7 @@ enum _LicenseEntryWithLineBreaksParserState { /// license per frame is reasonable; doing more at the same time is ill-advised. /// Consider doing all the work at once using [compute] to move the work to /// another thread, or spreading the work across multiple frames using -/// [scheduleTask]. +/// [SchedulerBinding.scheduleTask]. class LicenseEntryWithLineBreaks extends LicenseEntry { /// Create a license entry for a license whose text is hard-wrapped within /// paragraphs and has paragraph breaks denoted by blank lines or with diff --git a/packages/flutter/lib/src/foundation/platform.dart b/packages/flutter/lib/src/foundation/platform.dart index 6d845c738e0..8ce65f4b4b7 100644 --- a/packages/flutter/lib/src/foundation/platform.dart +++ b/packages/flutter/lib/src/foundation/platform.dart @@ -13,7 +13,7 @@ import '_platform_io.dart' /// platform for styling purposes, rather than using [defaultTargetPlatform]. /// Widgets and render objects at lower layers that try to emulate the /// underlying platform can depend on [defaultTargetPlatform] directly. The -/// [dart.io.Platform] object should only be used directly when it's critical to +/// [dart:io.Platform] object should only be used directly when it's critical to /// actually know the current platform, without any overrides possible (for /// example, when a system API is about to be called). /// diff --git a/packages/flutter/lib/src/gestures/events.dart b/packages/flutter/lib/src/gestures/events.dart index 409bed7537f..65e54e0b56c 100644 --- a/packages/flutter/lib/src/gestures/events.dart +++ b/packages/flutter/lib/src/gestures/events.dart @@ -257,11 +257,10 @@ abstract class PointerEvent extends Diagnosticable { /// system according to [transform]. /// /// If this event has not been transformed, [position] is returned as-is. - /// /// See also: /// - /// * [globalPosition], which is the position in the global coordinate - /// system of the screen. + /// * [position], which is the position in the global coordinate system of + /// the screen. final Offset localPosition; /// Distance in logical pixels that the pointer moved since the last @@ -420,7 +419,7 @@ abstract class PointerEvent extends Diagnosticable { /// Set if the event was synthesized by Flutter. /// /// We occasionally synthesize PointerEvents that aren't exact translations - /// of [ui.PointerData] from the engine to cover small cross-OS discrepancies + /// of [PointerData] from the engine to cover small cross-OS discrepancies /// in pointer behaviors. /// /// For instance, on end events, Android always drops any location changes diff --git a/packages/flutter/lib/src/gestures/force_press.dart b/packages/flutter/lib/src/gestures/force_press.dart index 0e30fab5f9e..9238e2237c3 100644 --- a/packages/flutter/lib/src/gestures/force_press.dart +++ b/packages/flutter/lib/src/gestures/force_press.dart @@ -43,7 +43,6 @@ enum _ForceState { /// * [ForcePressGestureRecognizer.onStart], [ForcePressGestureRecognizer.onPeak], /// [ForcePressGestureRecognizer.onEnd], and [ForcePressGestureRecognizer.onUpdate] /// which use [ForcePressDetails]. -/// * [ForcePressUpdateDetails], the details for [ForcePressUpdateCallback]. class ForcePressDetails { /// Creates details for a [GestureForcePressStartCallback], /// [GestureForcePressPeakCallback] or [GestureForcePressEndCallback]. @@ -152,7 +151,7 @@ class ForcePressGestureRecognizer extends OneSequenceGestureRecognizer { /// of [onStart] and/or [onPeak] and before the invocation of [onEnd], no /// matter what the pressure is during this time period. The position and /// pressure of the pointer is provided in the callback's `details` argument, - /// which is a [ForcePressUpdateDetails] object. + /// which is a [ForcePressDetails] object. GestureForcePressUpdateCallback onUpdate; /// A pointer is in contact with the screen and has just pressed with a force @@ -190,7 +189,7 @@ class ForcePressGestureRecognizer extends OneSequenceGestureRecognizer { /// /// This function must always return values in the range 0.0 to 1.0 given a /// pressure that is between the minimum and maximum pressures. It may return - /// [double.NaN] for values that it does not want to support. + /// `double.NaN` for values that it does not want to support. /// /// By default, the function is a linear interpolation; however, changing the /// function could be useful to accommodate variations in the way different diff --git a/packages/flutter/lib/src/gestures/hit_test.dart b/packages/flutter/lib/src/gestures/hit_test.dart index 9b834581965..891890dc5da 100644 --- a/packages/flutter/lib/src/gestures/hit_test.dart +++ b/packages/flutter/lib/src/gestures/hit_test.dart @@ -62,8 +62,8 @@ class HitTestEntry { /// /// See also: /// - /// * [HitTestResult.addWithPaintTransform], which is used during hit testing - /// to build up the transform returned by this method. + /// * [HitTestResult.pushTransform], which is used during hit + /// testing to build up the transform returned by this method. Matrix4 get transform => _transform; Matrix4 _transform; } @@ -129,7 +129,7 @@ class HitTestResult { /// * [BoxHitTestResult.addWithPaintTransform], which is a public wrapper /// around this function for hit testing on [RenderBox]s. /// * [SliverHitTestResult.addWithAxisOffset], which is a public wrapper - /// around this function for hit testing on [RenderSlivers]s. + /// around this function for hit testing on [RenderSliver]s. @protected void pushTransform(Matrix4 transform) { assert(transform != null); diff --git a/packages/flutter/lib/src/gestures/mouse_tracking.dart b/packages/flutter/lib/src/gestures/mouse_tracking.dart index f225ca0ecac..6dd128c78d0 100644 --- a/packages/flutter/lib/src/gestures/mouse_tracking.dart +++ b/packages/flutter/lib/src/gestures/mouse_tracking.dart @@ -106,7 +106,7 @@ class MouseTrackerAnnotation { /// annotation is attached, then you can call the callback when that /// condition goes from true to false. /// * In the cases where the solutions above won't work, you can always - /// override [Widget.dispose] or [RenderObject.detach]. + /// override [State.dispose] or [RenderObject.detach]. /// {@endtemplate} /// /// Technically, whether [onExit] will be called is controlled by diff --git a/packages/flutter/lib/src/gestures/multitap.dart b/packages/flutter/lib/src/gestures/multitap.dart index c2721a7caa0..57e9a7b5bfd 100644 --- a/packages/flutter/lib/src/gestures/multitap.dart +++ b/packages/flutter/lib/src/gestures/multitap.dart @@ -144,8 +144,8 @@ class DoubleTapGestureRecognizer extends GestureRecognizer { /// Called when the user has tapped the screen with a primary button at the /// same location twice in quick succession. /// - /// This triggers when the pointer stops contacting the device after the 2nd tap, - /// immediately after [onDoubleTapUp]. + /// This triggers when the pointer stops contacting the device after the + /// second tap. /// /// See also: /// diff --git a/packages/flutter/lib/src/gestures/tap.dart b/packages/flutter/lib/src/gestures/tap.dart index 8a19523716a..8c14b8fa96e 100644 --- a/packages/flutter/lib/src/gestures/tap.dart +++ b/packages/flutter/lib/src/gestures/tap.dart @@ -390,7 +390,7 @@ class TapGestureRecognizer extends BaseTapGestureRecognizer { /// See also: /// /// * [kSecondaryButton], the button this callback responds to. - /// * [onPrimaryTapDown], a similar callback but for a primary button. + /// * [onTapDown], a similar callback but for a primary button. /// * [TapDownDetails], which is passed as an argument to this callback. /// * [GestureDetector.onSecondaryTapDown], which exposes this callback. GestureTapDownCallback onSecondaryTapDown; @@ -407,7 +407,7 @@ class TapGestureRecognizer extends BaseTapGestureRecognizer { /// See also: /// /// * [kSecondaryButton], the button this callback responds to. - /// * [onPrimaryTapUp], a similar callback but for a primary button. + /// * [onTapUp], a similar callback but for a primary button. /// * [TapUpDetails], which is passed as an argument to this callback. /// * [GestureDetector.onSecondaryTapUp], which exposes this callback. GestureTapUpCallback onSecondaryTapUp; @@ -423,7 +423,7 @@ class TapGestureRecognizer extends BaseTapGestureRecognizer { /// See also: /// /// * [kSecondaryButton], the button this callback responds to. - /// * [onPrimaryTapCancel], a similar callback but for a primary button. + /// * [onTapCancel], a similar callback but for a primary button. /// * [GestureDetector.onTapCancel], which exposes this callback. GestureTapCancelCallback onSecondaryTapCancel; diff --git a/packages/flutter/lib/src/gestures/team.dart b/packages/flutter/lib/src/gestures/team.dart index a5da7e0fb18..2dcdd738a58 100644 --- a/packages/flutter/lib/src/gestures/team.dart +++ b/packages/flutter/lib/src/gestures/team.dart @@ -112,7 +112,7 @@ class _CombiningGestureArenaMember extends GestureArenaMember { /// /// [AndroidView] uses a team with a captain to decide which gestures are /// forwarded to the native view. For example if we want to forward taps and -/// vertical scrolls to a native Android view, [TapGestureRecognizers] and +/// vertical scrolls to a native Android view, [TapGestureRecognizer]s and /// [VerticalDragGestureRecognizer] are added to a team with a captain(the captain is set to be a /// gesture recognizer that never explicitly claims the gesture). /// The captain allows [AndroidView] to know when any gestures in the team has been diff --git a/packages/flutter/lib/src/material/bottom_app_bar.dart b/packages/flutter/lib/src/material/bottom_app_bar.dart index 73fe3475bb1..bb53bac8d60 100644 --- a/packages/flutter/lib/src/material/bottom_app_bar.dart +++ b/packages/flutter/lib/src/material/bottom_app_bar.dart @@ -35,9 +35,7 @@ import 'theme.dart'; /// /// See also: /// -/// * [ComputeNotch] a function used for creating a notch in a shape. -/// * [ScaffoldGeometry.floatingActionBarComputeNotch] the [ComputeNotch] used to -/// make a notch for the [FloatingActionButton]. +/// * [NotchedShape] which calculates the notch for a notched [BottomAppBar]. /// * [FloatingActionButton] which the [BottomAppBar] makes a notch for. /// * [AppBar] for a toolbar that is shown at the top of the screen. class BottomAppBar extends StatefulWidget { diff --git a/packages/flutter/lib/src/material/button_bar.dart b/packages/flutter/lib/src/material/button_bar.dart index 0391b23a053..03e5075de14 100644 --- a/packages/flutter/lib/src/material/button_bar.dart +++ b/packages/flutter/lib/src/material/button_bar.dart @@ -25,7 +25,7 @@ import 'raised_button.dart'; /// widget, it aligns its buttons in a column. The key difference here /// is that the [MainAxisAlignment] will then be treated as a /// cross-axis/horizontal alignment. For example, if the buttons overflow and -/// [ButtonBar.alignment] was set to [MainAxisAligment.start], the buttons would +/// [ButtonBar.alignment] was set to [MainAxisAlignment.start], the buttons would /// align to the horizontal start of the button bar. /// /// The [ButtonBar] can be configured with a [ButtonBarTheme]. For any null diff --git a/packages/flutter/lib/src/material/chip_theme.dart b/packages/flutter/lib/src/material/chip_theme.dart index 2dfa591e6d5..2a49299cf8b 100644 --- a/packages/flutter/lib/src/material/chip_theme.dart +++ b/packages/flutter/lib/src/material/chip_theme.dart @@ -23,7 +23,7 @@ import 'theme_data.dart'; /// rebuilt if the theme later changes. /// /// The [ThemeData] object given by the [Theme.of] call also contains a default -/// [Theme.chipTheme] that can be customized by copying it (using +/// [ThemeData.chipTheme] that can be customized by copying it (using /// [ChipThemeData.copyWith]). /// /// See also: diff --git a/packages/flutter/lib/src/material/dialog_theme.dart b/packages/flutter/lib/src/material/dialog_theme.dart index edc8e645b33..f67b21362c1 100644 --- a/packages/flutter/lib/src/material/dialog_theme.dart +++ b/packages/flutter/lib/src/material/dialog_theme.dart @@ -18,8 +18,8 @@ import 'theme.dart'; /// When Shape is `null`, the dialog defaults to a [RoundedRectangleBorder] with /// a border radius of 2.0 on all corners. /// -/// [titleTextStyle] and [contentTextStyle] are used in [AlertDialogs]. -/// If null, they default to [ThemeData.textTheme.title] and [ThemeData.textTheme.subhead], +/// [titleTextStyle] and [contentTextStyle] are used in [AlertDialog]s. +/// If null, they default to [TextTheme.title] and [TextTheme.subhead], /// respectively. /// /// See also: diff --git a/packages/flutter/lib/src/material/divider_theme.dart b/packages/flutter/lib/src/material/divider_theme.dart index 598b442ba98..44b7d44c290 100644 --- a/packages/flutter/lib/src/material/divider_theme.dart +++ b/packages/flutter/lib/src/material/divider_theme.dart @@ -130,11 +130,11 @@ class DividerThemeData extends Diagnosticable { } /// An inherited widget that defines the configuration for -/// [Divider]s, [VerticalDividers]s, dividers between [ListTile]s, and dividers +/// [Divider]s, [VerticalDivider]s, dividers between [ListTile]s, and dividers /// between rows in [DataTable]s in this widget's subtree. class DividerTheme extends InheritedTheme { /// Creates a divider theme that controls the configurations for - /// [Divider]s, [VerticalDividers]s, dividers between [ListTile]s, and dividers + /// [Divider]s, [VerticalDivider]s, dividers between [ListTile]s, and dividers /// between rows in [DataTable]s in its widget subtree. const DividerTheme({ Key key, @@ -143,7 +143,7 @@ class DividerTheme extends InheritedTheme { }) : assert(data != null), super(key: key, child: child); - /// The properties for descendant [Divider]s, [VerticalDividers]s, dividers + /// The properties for descendant [Divider]s, [VerticalDivider]s, dividers /// between [ListTile]s, and dividers between rows in [DataTable]s. final DividerThemeData data; diff --git a/packages/flutter/lib/src/material/icons.dart b/packages/flutter/lib/src/material/icons.dart index 42ed7cefc1b..6bb22253806 100644 --- a/packages/flutter/lib/src/material/icons.dart +++ b/packages/flutter/lib/src/material/icons.dart @@ -23,7 +23,7 @@ import 'package:flutter/widgets.dart'; /// /// {@tool sample} /// This example shows how to create a [Row] of [Icon]s in different colors and -/// sizes. The first [Icon] uses a [semanticLabel] to announce in accessibility +/// sizes. The first [Icon] uses a [Icon.semanticLabel] to announce in accessibility /// modes like TalkBack and VoiceOver. /// /// ![A row of icons representing a pink heart, a green musical note, and a blue umbrella](https://flutter.github.io/assets-for-api-docs/assets/widgets/icon.png) diff --git a/packages/flutter/lib/src/material/material_localizations.dart b/packages/flutter/lib/src/material/material_localizations.dart index e322a9e44ef..f052226189e 100644 --- a/packages/flutter/lib/src/material/material_localizations.dart +++ b/packages/flutter/lib/src/material/material_localizations.dart @@ -177,7 +177,7 @@ abstract class MaterialLocalizations { /// Defines the localized [TextStyle] geometry for [ThemeData.textTheme]. /// /// The [scriptCategory] defines the overall geometry of a [TextTheme] for - /// the static [MaterialTextGeometry.localizedFor] method in terms of the + /// the [Typography.geometryThemeFor] method in terms of the /// three language categories defined in https://material.io/go/design-typography. /// /// Generally speaking, font sizes for [ScriptCategory.tall] and @@ -353,7 +353,7 @@ class _MaterialLocalizationsDelegate extends LocalizationsDelegate { /// Used by [PageTransitionsTheme] to define a [MaterialPageRoute] page /// transition animation. /// -/// Apps can configure the map of builders for [ThemeData.platformTheme] +/// Apps can configure the map of builders for [ThemeData.pageTransitionsTheme] /// to customize the default [MaterialPageRoute] page transition animation /// for different platforms. /// diff --git a/packages/flutter/lib/src/material/selectable_text.dart b/packages/flutter/lib/src/material/selectable_text.dart index e777484a6bf..068b8e672e6 100644 --- a/packages/flutter/lib/src/material/selectable_text.dart +++ b/packages/flutter/lib/src/material/selectable_text.dart @@ -376,7 +376,7 @@ class SelectableText extends StatefulWidget { /// selectable text's internal gesture detector, use a [Listener]. final GestureTapCallback onTap; - /// {@macro flutter.widgets.edtiableText.scrollPhysics} + /// {@macro flutter.widgets.editableText.scrollPhysics} final ScrollPhysics scrollPhysics; /// {@macro flutter.painting.textPainter.textWidthBasis} diff --git a/packages/flutter/lib/src/material/text_field.dart b/packages/flutter/lib/src/material/text_field.dart index 97f37cf7922..c7fa57ea15d 100644 --- a/packages/flutter/lib/src/material/text_field.dart +++ b/packages/flutter/lib/src/material/text_field.dart @@ -444,7 +444,7 @@ class TextField extends StatefulWidget { /// {@macro flutter.widgets.editableText.textAlign} final TextAlign textAlign; - /// {@macro flutter.material.inputDecorator.textAlignVertical} + /// {@macro flutter.widgets.inputDecorator.textAlignVertical} final TextAlignVertical textAlignVertical; /// {@macro flutter.widgets.editableText.textDirection} @@ -663,7 +663,7 @@ class TextField extends StatefulWidget { /// {@end-tool} final InputCounterWidgetBuilder buildCounter; - /// {@macro flutter.widgets.edtiableText.scrollPhysics} + /// {@macro flutter.widgets.editableText.scrollPhysics} final ScrollPhysics scrollPhysics; /// {@macro flutter.widgets.editableText.scrollController} diff --git a/packages/flutter/lib/src/material/typography.dart b/packages/flutter/lib/src/material/typography.dart index 02dedf439d3..b44ab330652 100644 --- a/packages/flutter/lib/src/material/typography.dart +++ b/packages/flutter/lib/src/material/typography.dart @@ -12,7 +12,7 @@ import 'text_theme.dart'; /// its localized [TextStyle] geometry for [ThemeData.textTheme]. /// /// The script category defines the overall geometry of a [TextTheme] for -/// the static [MaterialTextGeometry.localizedFor] method in terms of the +/// the [Typography.geometryThemeFor] method in terms of the /// three language categories defined in . /// /// Generally speaking, font sizes for [ScriptCategory.tall] and diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart index d6d46ebbef4..c5ebbd537aa 100644 --- a/packages/flutter/lib/src/rendering/object.dart +++ b/packages/flutter/lib/src/rendering/object.dart @@ -2702,7 +2702,7 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im /// /// If [isSemanticBoundary] is true, this method is called with the `node` /// created for this [RenderObject], the `config` to be applied to that node - /// and the `children` [SemanticNode]s that descendants of this RenderObject + /// and the `children` [SemanticsNode]s that descendants of this RenderObject /// have generated. /// /// By default, the method will annotate `node` with `config` and add the @@ -3419,7 +3419,7 @@ abstract class _InterestingSemanticsFragment extends _SemanticsFragment { _ancestorChain = [owner], super(dropsSemanticsOfPreviousSiblings: dropsSemanticsOfPreviousSiblings); - /// The [RenderObject] that owns this fragment (and any new [SemanticNode] + /// The [RenderObject] that owns this fragment (and any new [SemanticsNode] /// introduced by it). RenderObject get owner => _ancestorChain.first; diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 4bea5e36f57..d9f000fbbcc 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -3636,15 +3636,16 @@ class RenderSemanticsAnnotations extends RenderProxyBox { /// Whether descendants of this [RenderObject] are allowed to add semantic /// information to the [SemanticsNode] annotated by this widget. /// - /// When set to false descendants are allowed to annotate [SemanticNode]s of + /// When set to false descendants are allowed to annotate [SemanticsNode]s of /// their parent with the semantic information they want to contribute to the /// semantic tree. /// When set to true the only way for descendants to contribute semantic /// information to the semantic tree is to introduce new explicit - /// [SemanticNode]s to the tree. + /// [SemanticsNode]s to the tree. /// - /// This setting is often used in combination with [isSemanticBoundary] to - /// create semantic boundaries that are either writable or not for children. + /// This setting is often used in combination with + /// [SemanticsConfiguration.isSemanticBoundary] to create semantic boundaries + /// that are either writable or not for children. bool get explicitChildNodes => _explicitChildNodes; bool _explicitChildNodes; set explicitChildNodes(bool value) { @@ -3671,8 +3672,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox { markNeedsSemanticsUpdate(); } - /// If non-null, sets the [SemanticsNode.hasCheckedState] semantic to true and - /// the [SemanticsNode.isChecked] semantic to the given value. + /// If non-null, sets the [SemanticsFlag.hasCheckedState] semantic to true and + /// the [SemanticsConfiguration.isChecked] semantic to the given value. bool get checked => _checked; bool _checked; set checked(bool value) { @@ -3682,8 +3683,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox { markNeedsSemanticsUpdate(); } - /// If non-null, sets the [SemanticsNode.hasEnabledState] semantic to true and - /// the [SemanticsNode.isEnabled] semantic to the given value. + /// If non-null, sets the [SemanticsFlag.hasEnabledState] semantic to true and + /// the [SemanticsConfiguration.isEnabled] semantic to the given value. bool get enabled => _enabled; bool _enabled; set enabled(bool value) { @@ -3693,8 +3694,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox { markNeedsSemanticsUpdate(); } - /// If non-null, sets the [SemanticsNode.isSelected] semantic to the given - /// value. + /// If non-null, sets the [SemanticsConfiguration.isSelected] semantic to the + /// given value. bool get selected => _selected; bool _selected; set selected(bool value) { @@ -3704,7 +3705,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox { markNeedsSemanticsUpdate(); } - /// If non-null, sets the [SemanticsNode.isButton] semantic to the given value. + /// If non-null, sets the [SemanticsConfiguration.isButton] semantic to the + /// given value. bool get button => _button; bool _button; set button(bool value) { @@ -3848,7 +3850,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox { _image = value; } - /// If non-null, sets the [SemanticsNode.isLiveRegion] semantic to the given + /// If non-null, sets the [SemanticsFlag.isLiveRegion] semantic to the given /// value. bool get liveRegion => _liveRegion; bool _liveRegion; diff --git a/packages/flutter/lib/src/scheduler/binding.dart b/packages/flutter/lib/src/scheduler/binding.dart index 828da0fdb04..31f43ab9104 100644 --- a/packages/flutter/lib/src/scheduler/binding.dart +++ b/packages/flutter/lib/src/scheduler/binding.dart @@ -417,7 +417,8 @@ mixin SchedulerBinding on BindingBase, ServicesBinding { // Whether this scheduler already requested to be called from the event loop. bool _hasRequestedAnEventLoopCallback = false; - // Ensures that the scheduler services a task scheduled by [scheduleTask]. + // Ensures that the scheduler services a task scheduled by + // [SchedulerBinding.scheduleTask]. void _ensureEventLoopCallback() { assert(!locked); assert(_taskQueue.isNotEmpty); diff --git a/packages/flutter/lib/src/semantics/semantics.dart b/packages/flutter/lib/src/semantics/semantics.dart index 93e67d7e825..271cd1c14d0 100644 --- a/packages/flutter/lib/src/semantics/semantics.dart +++ b/packages/flutter/lib/src/semantics/semantics.dart @@ -2776,11 +2776,11 @@ class SemanticsConfiguration { /// so in the form of explicit [SemanticsNode]s. /// /// When set to false children of the owning [RenderObject] are allowed to - /// annotate [SemanticNode]s of their parent with the semantic information + /// annotate [SemanticsNode]s of their parent with the semantic information /// they want to contribute to the semantic tree. /// When set to true the only way for children of the owning [RenderObject] /// to contribute semantic information to the semantic tree is to introduce - /// new explicit [SemanticNode]s to the tree. + /// new explicit [SemanticsNode]s to the tree. /// /// This setting is often used in combination with [isSemanticBoundary] to /// create semantic boundaries that are either writable or not for children. @@ -2804,7 +2804,7 @@ class SemanticsConfiguration { bool isBlockingSemanticsOfPreviouslyPaintedNodes = false; // SEMANTIC ANNOTATIONS - // These will end up on [SemanticNode]s generated from + // These will end up on [SemanticsNode]s generated from // [SemanticsConfiguration]s. /// Whether this configuration is empty. diff --git a/packages/flutter/lib/src/widgets/app.dart b/packages/flutter/lib/src/widgets/app.dart index 9f0bd6df3f7..ff02c8dfde7 100644 --- a/packages/flutter/lib/src/widgets/app.dart +++ b/packages/flutter/lib/src/widgets/app.dart @@ -49,6 +49,7 @@ export 'dart:ui' show Locale; /// is recommended over [LocaleResolutionCallback]. typedef LocaleListResolutionCallback = Locale Function(List locales, Iterable supportedLocales); +/// {@template flutter.widgets.widgetsApp.localeResolutionCallback} /// The signature of [WidgetsApp.localeResolutionCallback]. /// /// It is recommended to provide a [LocaleListResolutionCallback] instead of a @@ -73,6 +74,7 @@ typedef LocaleListResolutionCallback = Locale Function(List locales, Ite /// /// * [LocaleListResolutionCallback], which takes a list of preferred locales (instead of one locale). /// Resolutions by [LocaleListResolutionCallback] take precedence over [LocaleResolutionCallback]. +/// {@endtemplate} typedef LocaleResolutionCallback = Locale Function(Locale locale, Iterable supportedLocales); /// The signature of [WidgetsApp.onGenerateTitle]. @@ -487,7 +489,7 @@ class WidgetsApp extends StatefulWidget { /// /// The value of [Localizations.locale] will equal this locale if /// it matches one of the [supportedLocales]. Otherwise it will be - /// the first [supportedLocale]. + /// the first element of [supportedLocales]. /// {@endtemplate} /// /// See also: @@ -511,22 +513,25 @@ class WidgetsApp extends StatefulWidget { /// when the app is started, and when the user changes the /// device's locale. /// - /// When a [localeListResolutionCallback] is provided, Flutter will first attempt to - /// resolve the locale with the provided [localeListResolutionCallback]. If the - /// callback or result is null, it will fallback to trying the [localeResolutionCallback]. - /// If both [localeResolutionCallback] and [localeListResolutionCallback] are left null - /// or fail to resolve (return null), the [WidgetsApp.basicLocaleListResolution] - /// fallback algorithm will be used. + /// When a [localeListResolutionCallback] is provided, Flutter will first + /// attempt to resolve the locale with the provided + /// [localeListResolutionCallback]. If the callback or result is null, it will + /// fallback to trying the [localeResolutionCallback]. If both + /// [localeResolutionCallback] and [localeListResolutionCallback] are left + /// null or fail to resolve (return null), the a basic fallback algorithm will + /// be used. /// /// The priority of each available fallback is: /// /// 1. [localeListResolutionCallback] is attempted first. - /// 2. [localeResolutionCallback] is attempted second. - /// 3. Flutter's [WidgetsApp.basicLocaleListResolution] algorithm is attempted last. + /// 1. [localeResolutionCallback] is attempted second. + /// 1. Flutter's basic resolution algorithm, as described in + /// [supportedLocales], is attempted last. /// /// Properly localized projects should provide a more advanced algorithm than - /// [basicLocaleListResolution] as it does not implement a complete algorithm - /// (such as the one defined in [Unicode TR35](https://unicode.org/reports/tr35/#LanguageMatching)) + /// the basic method from [supportedLocales], as it does not implement a + /// complete algorithm (such as the one defined in + /// [Unicode TR35](https://unicode.org/reports/tr35/#LanguageMatching)) /// and is optimized for speed at the detriment of some uncommon edge-cases. /// {@endtemplate} /// @@ -539,8 +544,6 @@ class WidgetsApp extends StatefulWidget { /// /// * [MaterialApp.localeListResolutionCallback], which sets the callback of the /// [WidgetsApp] it creates. - /// * [basicLocaleListResolution], a static method that implements the locale resolution - /// algorithm that is used when no custom locale resolution algorithm is provided. final LocaleListResolutionCallback localeListResolutionCallback; /// {@macro flutter.widgets.widgetsApp.localeListResolutionCallback} @@ -556,8 +559,6 @@ class WidgetsApp extends StatefulWidget { /// /// * [MaterialApp.localeResolutionCallback], which sets the callback of the /// [WidgetsApp] it creates. - /// * [basicLocaleListResolution], a static method that implements the locale resolution - /// algorithm that is used when no custom locale resolution algorithm is provided. final LocaleResolutionCallback localeResolutionCallback; /// {@template flutter.widgets.widgetsApp.supportedLocales} @@ -570,24 +571,24 @@ class WidgetsApp extends StatefulWidget { /// `[const Locale('en', 'US')]`. /// /// The order of the list matters. The default locale resolution algorithm, - /// [basicLocaleListResolution], attempts to match by the following priority: + /// `basicLocaleListResolution`, attempts to match by the following priority: /// /// 1. [Locale.languageCode], [Locale.scriptCode], and [Locale.countryCode] - /// 2. [Locale.languageCode] and [Locale.countryCode] only - /// 3. [Locale.languageCode] and [Locale.countryCode] only - /// 4. [Locale.languageCode] only - /// 6. [Locale.countryCode] only when all [preferredLocales] fail to match - /// 5. returns [supportedLocales.first] as a fallback + /// 1. [Locale.languageCode] and [Locale.countryCode] only + /// 1. [Locale.languageCode] and [Locale.countryCode] only + /// 1. [Locale.languageCode] only + /// 1. [Locale.countryCode] only when all preferred locales fail to match + /// 1. Returns the first element of [supportedLocales] as a fallback /// - /// When more than one supported locale matches one of these criteria, only the first - /// matching locale is returned. See [basicLocaleListResolution] for a complete - /// description of the algorithm. + /// When more than one supported locale matches one of these criteria, only + /// the first matching locale is returned. /// - /// The default locale resolution algorithm can be overridden by providing a value for - /// [localeListResolutionCallback]. The provided [basicLocaleListResolution] is optimized - /// for speed and does not implement a full algorithm (such as the one defined in - /// [Unicode TR35](https://unicode.org/reports/tr35/#LanguageMatching)) that takes - /// distances between languages into account. + /// The default locale resolution algorithm can be overridden by providing a + /// value for [localeListResolutionCallback]. The provided + /// `basicLocaleListResolution` is optimized for speed and does not implement + /// a full algorithm (such as the one defined in + /// [Unicode TR35](https://unicode.org/reports/tr35/#LanguageMatching)) that + /// takes distances between languages into account. /// /// When supporting languages with more than one script, it is recommended /// to specify the [Locale.scriptCode] explicitly. Locales may also be defined without @@ -626,8 +627,6 @@ class WidgetsApp extends StatefulWidget { /// when the device's locale changes. /// * [localizationsDelegates], which collectively define all of the localized /// resources used by this app. - /// * [basicLocaleListResolution], a static method that implements the locale resolution - /// algorithm that is used when no custom locale resolution algorithm is provided. final Iterable supportedLocales; /// Turns on a performance overlay. @@ -847,40 +846,41 @@ class _WidgetsAppState extends State with WidgetsBindingObserver { /// The default locale resolution algorithm. /// - /// Custom resolution algorithms can be provided through [WidgetsApp.localeListResolutionCallback] - /// or [WidgetsApp.localeResolutionCallback]. + /// Custom resolution algorithms can be provided through + /// [WidgetsApp.localeListResolutionCallback] or + /// [WidgetsApp.localeResolutionCallback]. /// - /// When no custom locale resolution algorithms are provided or if both fail to resolve, - /// Flutter will default to calling this algorithm. + /// When no custom locale resolution algorithms are provided or if both fail + /// to resolve, Flutter will default to calling this algorithm. /// /// This algorithm prioritizes speed at the cost of slightly less appropriate /// resolutions for edge cases. /// - /// This algorithm will resolve to the earliest locale in [preferredLocales] that + /// This algorithm will resolve to the earliest preferred locale that /// matches the most fields, prioritizing in the order of perfect match, /// languageCode+countryCode, languageCode+scriptCode, languageCode-only. /// /// In the case where a locale is matched by languageCode-only and is not the - /// default (first) locale, the next locale in preferredLocales with a + /// default (first) locale, the next preferred locale with a /// perfect match can supersede the languageCode-only match if it exists. /// - /// When a preferredLocale matches more than one supported locale, it will resolve - /// to the first matching locale listed in the supportedLocales. + /// When a preferredLocale matches more than one supported locale, it will + /// resolve to the first matching locale listed in the supportedLocales. /// - /// When all [preferredLocales] have been exhausted without a match, the first countryCode only - /// match will be returned. + /// When all preferred locales have been exhausted without a match, the first + /// countryCode only match will be returned. /// - /// When no match at all is found, the first (default) locale in [supportedLocales] will be - /// returned. + /// When no match at all is found, the first (default) locale in + /// [supportedLocales] will be returned. /// /// To summarize, the main matching priority is: /// /// 1. [Locale.languageCode], [Locale.scriptCode], and [Locale.countryCode] - /// 2. [Locale.languageCode] and [Locale.scriptCode] only - /// 3. [Locale.languageCode] and [Locale.countryCode] only - /// 4. [Locale.languageCode] only (with caveats, see above) - /// 5. [Locale.countryCode] only when all [preferredLocales] fail to match - /// 6. returns [supportedLocales.first] as a fallback + /// 1. [Locale.languageCode] and [Locale.scriptCode] only + /// 1. [Locale.languageCode] and [Locale.countryCode] only + /// 1. [Locale.languageCode] only (with caveats, see above) + /// 1. [Locale.countryCode] only when all [preferredLocales] fail to match + /// 1. Returns the first element of [supportedLocales] as a fallback /// /// This algorithm does not take language distance (how similar languages are to each other) /// into account, and will not handle edge cases such as resolving `de` to `fr` rather than `zh` diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 85e65c3fab2..f6cfdf2335c 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -6416,12 +6416,12 @@ class Semantics extends SingleChildRenderObjectWidget { /// Whether descendants of this widget are allowed to add semantic information /// to the [SemanticsNode] annotated by this widget. /// - /// When set to false descendants are allowed to annotate [SemanticNode]s of + /// When set to false descendants are allowed to annotate [SemanticsNode]s of /// their parent with the semantic information they want to contribute to the /// semantic tree. /// When set to true the only way for descendants to contribute semantic /// information to the semantic tree is to introduce new explicit - /// [SemanticNode]s to the tree. + /// [SemanticsNode]s to the tree. /// /// If the semantics properties of this node include /// [SemanticsProperties.scopesRoute] set to true, then [explicitChildNodes] diff --git a/packages/flutter/lib/src/widgets/editable_text.dart b/packages/flutter/lib/src/widgets/editable_text.dart index c2996d6ceab..4603e0446b5 100644 --- a/packages/flutter/lib/src/widgets/editable_text.dart +++ b/packages/flutter/lib/src/widgets/editable_text.dart @@ -503,11 +503,11 @@ class EditableText extends StatefulWidget { /// Whether to show cursor. /// /// The cursor refers to the blinking caret when the [EditableText] is focused. + /// {@endtemplate} /// /// See also: /// /// * [showSelectionHandles], which controls the visibility of the selection handles. - /// {@endtemplate} final bool showCursor; /// {@template flutter.widgets.editableText.autocorrect} diff --git a/packages/flutter/lib/src/widgets/widget_inspector.dart b/packages/flutter/lib/src/widgets/widget_inspector.dart index f0b484a67d3..eb7adcd4306 100644 --- a/packages/flutter/lib/src/widgets/widget_inspector.dart +++ b/packages/flutter/lib/src/widgets/widget_inspector.dart @@ -1662,7 +1662,7 @@ mixin WidgetInspectorService { /// /// If the currently selected [RenderObject] is identical to the /// [RenderObject] referenced by `previousSelectionId` then the previous - /// [DiagnosticNode] is reused. + /// [DiagnosticsNode] is reused. @protected String getSelectedRenderObject(String previousSelectionId, String groupName) { return _safeJsonEncode(_getSelectedRenderObject(previousSelectionId, groupName)); @@ -1677,7 +1677,7 @@ mixin WidgetInspectorService { /// Returns a [DiagnosticsNode] representing the currently selected [Element]. /// /// If the currently selected [Element] is identical to the [Element] - /// referenced by `previousSelectionId` then the previous [DiagnosticNode] is + /// referenced by `previousSelectionId` then the previous [DiagnosticsNode] is /// reused. @protected String getSelectedWidget(String previousSelectionId, String groupName) { @@ -1767,7 +1767,7 @@ mixin WidgetInspectorService { /// tree. /// /// If the currently selected [Element] is identical to the [Element] - /// referenced by `previousSelectionId` then the previous [DiagnosticNode] is + /// referenced by `previousSelectionId` then the previous [DiagnosticsNode] is /// reused. String getSelectedSummaryWidget(String previousSelectionId, String groupName) { return _safeJsonEncode(_getSelectedSummaryWidget(previousSelectionId, groupName));