diff --git a/dev/benchmarks/macrobenchmarks/lib/src/web/bench_image_decoding.dart b/dev/benchmarks/macrobenchmarks/lib/src/web/bench_image_decoding.dart index 18792d55001a..fc478993ce45 100644 --- a/dev/benchmarks/macrobenchmarks/lib/src/web/bench_image_decoding.dart +++ b/dev/benchmarks/macrobenchmarks/lib/src/web/bench_image_decoding.dart @@ -8,18 +8,18 @@ import 'dart:ui' as ui; import 'recorder.dart'; -/// Measures the performance of image decoding. -/// -/// The benchmark measures the decoding latency and not impact on jank. It -/// cannot distinguish between blocking and non-blocking decoding. It simply -/// measures the total time it takes to decode image frames. For example, the -/// WASM codecs execute on the main thread and block the UI, leading to jank, -/// but the browser's WebCodecs API is asynchronous running on a separate thread -/// and does not jank. However, the benchmark result may be the same. -/// -/// This benchmark does not support the HTML renderer because the HTML renderer -/// cannot decode image frames (it always returns 1 dummy frame, even for -/// animated images). +// Measures the performance of image decoding. +// +// The benchmark measures the decoding latency and not impact on jank. It +// cannot distinguish between blocking and non-blocking decoding. It naively +// measures the total time it takes to decode image frames. For example, the +// WASM codecs execute on the main thread and block the UI, leading to jank, +// but the browser's WebCodecs API is asynchronous running on a separate thread +// and does not jank. However, the benchmark result may be the same. +// +// This benchmark does not support the HTML renderer because the HTML renderer +// cannot decode image frames (it always returns 1 dummy frame, even for +// animated images). class BenchImageDecoding extends RawRecorder { BenchImageDecoding() : super( name: benchmarkName, diff --git a/dev/bots/analyze.dart b/dev/bots/analyze.dart index f6c9ec227d04..3e098cb4ea00 100644 --- a/dev/bots/analyze.dart +++ b/dev/bots/analyze.dart @@ -143,6 +143,9 @@ Future run(List arguments) async { printProgress('null initialized debug fields...'); await verifyNullInitializedDebugExpensiveFields(flutterRoot); + printProgress('Taboo words...'); + await verifyTabooDocumentation(flutterRoot); + // Ensure that all package dependencies are in sync. printProgress('Package dependencies...'); await runCommand(flutter, ['update-packages', '--verify-only'], @@ -1815,18 +1818,17 @@ Future verifyNullInitializedDebugExpensiveFields(String workingDirectory, final List errors = []; for (final File file in files) { final List lines = file.readAsLinesSync(); - for (int i = 0; i < lines.length; i += 1) { - final String line = lines[i]; + for (int index = 0; index < lines.length; index += 1) { + final String line = lines[index]; if (!line.contains(_kDebugOnlyAnnotation)) { continue; } - final String nextLine = lines[i + 1]; + final String nextLine = lines[index + 1]; if (_nullInitializedField.firstMatch(nextLine) == null) { - errors.add('${file.path} L$i'); + errors.add('${file.path}:$index'); } } } - if (errors.isNotEmpty) { foundError([ '${bold}ERROR: ${red}fields annotated with @_debugOnly must null initialize.$reset', @@ -1839,6 +1841,29 @@ Future verifyNullInitializedDebugExpensiveFields(String workingDirectory, } } +final RegExp tabooPattern = RegExp(r'^ *///.*\b(simply)\b', caseSensitive: false); + +Future verifyTabooDocumentation(String workingDirectory, { int minimumMatches = 100 }) async { + final List errors = []; + await for (final File file in _allFiles(workingDirectory, 'dart', minimumMatches: minimumMatches)) { + final List lines = file.readAsLinesSync(); + for (int index = 0; index < lines.length; index += 1) { + final String line = lines[index]; + final Match? match = tabooPattern.firstMatch(line); + if (match != null) { + errors.add('${file.path}:${index + 1}: Found use of the taboo word "${match.group(1)}" in documentation string.'); + } + } + } + if (errors.isNotEmpty) { + foundError([ + '${bold}Avoid the word "simply" in documentation. See https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#use-the-passive-voice-recommend-do-not-require-never-say-things-are-simple for details.$reset', + '${bold}In many cases the word can be omitted without loss of generality; in other cases it may require a bit of rewording to avoid implying that the task is simple.$reset', + ...errors, + ]); + } +} + Future _runFlutterAnalyze(String workingDirectory, { List options = const [], }) async { diff --git a/dev/bots/test/analyze-test-input/root/packages/flutter/lib/bar.dart b/dev/bots/test/analyze-test-input/root/packages/flutter/lib/bar.dart index 52fe6897a0eb..2b14c6f4c2d7 100644 --- a/dev/bots/test/analyze-test-input/root/packages/flutter/lib/bar.dart +++ b/dev/bots/test/analyze-test-input/root/packages/flutter/lib/bar.dart @@ -16,3 +16,6 @@ class Foo { @_debugOnly final Map? bar = kDebugMode ? null : {}; } + +/// Simply avoid this +/// and simply do that. diff --git a/dev/bots/test/analyze_test.dart b/dev/bots/test/analyze_test.dart index ace3c7a3fead..1eaa13b1e8ba 100644 --- a/dev/bots/test/analyze_test.dart +++ b/dev/bots/test/analyze_test.dart @@ -176,7 +176,18 @@ void main() { minimumMatches: 1, ), shouldHaveErrors: true); - expect(result, contains('L15')); - expect(result, isNot(contains('L12'))); + expect(result, contains(':15')); + expect(result, isNot(contains(':12'))); + }); + + test('analyze.dart - verifyTabooDocumentation', () async { + final String result = await capture(() => verifyTabooDocumentation( + testRootPath, + minimumMatches: 1, + ), shouldHaveErrors: true); + + expect(result, isNot(contains(':19'))); + expect(result, contains(':20')); + expect(result, contains(':21')); }); } diff --git a/packages/flutter/lib/src/animation/animations.dart b/packages/flutter/lib/src/animation/animations.dart index 2d6b6003965e..0eab6b800651 100644 --- a/packages/flutter/lib/src/animation/animations.dart +++ b/packages/flutter/lib/src/animation/animations.dart @@ -255,8 +255,8 @@ class ProxyAnimation extends Animation /// If the parent animation is running forward from 0.0 to 1.0, this animation /// is running in reverse from 1.0 to 0.0. /// -/// Using a [ReverseAnimation] is different from simply using a [Tween] with a -/// begin of 1.0 and an end of 0.0 because the tween does not change the status +/// Using a [ReverseAnimation] is different from using a [Tween] with a +/// `begin` of 1.0 and an `end` of 0.0 because the tween does not change the status /// or direction of the animation. /// /// See also: diff --git a/packages/flutter/lib/src/cupertino/context_menu.dart b/packages/flutter/lib/src/cupertino/context_menu.dart index 9e673355c25a..5a6024b0936c 100644 --- a/packages/flutter/lib/src/cupertino/context_menu.dart +++ b/packages/flutter/lib/src/cupertino/context_menu.dart @@ -99,10 +99,10 @@ enum _ContextMenuLocation { /// [Expanded] widget so that it will grow to fill the Overlay if its size is /// unconstrained. /// -/// When closed, the CupertinoContextMenu simply displays the child as if the -/// CupertinoContextMenu were not there. Sizing and positioning is unaffected. +/// When closed, the [CupertinoContextMenu] displays the child as if the +/// [CupertinoContextMenu] were not there. Sizing and positioning is unaffected. /// The menu can be closed like other [PopupRoute]s, such as by tapping the -/// background or by calling `Navigator.pop(context)`. Unlike PopupRoute, it can +/// background or by calling `Navigator.pop(context)`. Unlike [PopupRoute], it can /// also be closed by swiping downwards. /// /// The [previewBuilder] parameter is most commonly used to display a slight @@ -111,8 +111,8 @@ enum _ContextMenuLocation { /// Photos app on iOS. /// /// {@tool dartpad} -/// This sample shows a very simple CupertinoContextMenu for the Flutter logo. -/// Simply long press on it to open. +/// This sample shows a very simple [CupertinoContextMenu] for the Flutter logo. +/// Long press on it to open. /// /// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.0.dart ** /// {@end-tool} @@ -256,10 +256,9 @@ class CupertinoContextMenu extends StatefulWidget { /// and when it is fully open. This will overwrite the default animation that /// matches the behavior of an iOS 16.0 context menu. /// - /// This builder can be used instead of the child when either the intended - /// child has a property that would conflict with the default animation, like - /// a border radius or a shadow, or if simply a more custom animation is - /// needed. + /// This builder can be used instead of the child when the intended child has + /// a property that would conflict with the default animation, such as a + /// border radius or a shadow, or if a more custom animation is needed. /// /// In addition to the current [BuildContext], the function is also called /// with an [Animation]. The complete animation goes from 0 to 1 when diff --git a/packages/flutter/lib/src/cupertino/scrollbar.dart b/packages/flutter/lib/src/cupertino/scrollbar.dart index 34109290f12d..1b847f249912 100644 --- a/packages/flutter/lib/src/cupertino/scrollbar.dart +++ b/packages/flutter/lib/src/cupertino/scrollbar.dart @@ -29,7 +29,7 @@ const double _kScrollbarCrossAxisMargin = 3.0; /// An iOS style scrollbar. /// -/// To add a scrollbar to a [ScrollView], simply wrap the scroll view widget in +/// To add a scrollbar to a [ScrollView], wrap the scroll view widget in /// a [CupertinoScrollbar] widget. /// /// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc} diff --git a/packages/flutter/lib/src/cupertino/text_form_field_row.dart b/packages/flutter/lib/src/cupertino/text_form_field_row.dart index a77669da5f1d..9a8ca8600fb2 100644 --- a/packages/flutter/lib/src/cupertino/text_form_field_row.dart +++ b/packages/flutter/lib/src/cupertino/text_form_field_row.dart @@ -13,7 +13,7 @@ import 'text_field.dart'; /// Creates a [CupertinoFormRow] containing a [FormField] that wraps /// a [CupertinoTextField]. /// -/// A [Form] ancestor is not required. The [Form] simply makes it easier to +/// A [Form] ancestor is not required. The [Form] allows one to /// save, reset, or validate multiple fields at once. To use without a [Form], /// pass a [GlobalKey] to the constructor and use [GlobalKey.currentState] to /// save or reset the form field. diff --git a/packages/flutter/lib/src/foundation/assertions.dart b/packages/flutter/lib/src/foundation/assertions.dart index c95e64ce481f..49d9b953315d 100644 --- a/packages/flutter/lib/src/foundation/assertions.dart +++ b/packages/flutter/lib/src/foundation/assertions.dart @@ -140,7 +140,7 @@ class RepetitiveStackFrameFilter extends StackFilter { /// The string to replace the frames with. /// /// If the same replacement string is used multiple times in a row, the - /// [FlutterError.defaultStackFilter] will simply update a counter after this + /// [FlutterError.defaultStackFilter] will insert a repeat count after this /// line rather than repeating it. final String replacement; diff --git a/packages/flutter/lib/src/gestures/tap.dart b/packages/flutter/lib/src/gestures/tap.dart index 6d7910832907..a05d839cfaee 100644 --- a/packages/flutter/lib/src/gestures/tap.dart +++ b/packages/flutter/lib/src/gestures/tap.dart @@ -216,7 +216,7 @@ abstract class BaseTapGestureRecognizer extends PrimaryPointerGestureRecognizer if (_down != null) { // This happens when this tap gesture has been rejected while the pointer // is down (i.e. due to movement), when another allowed pointer is added, - // in which case all pointers are simply ignored. The `_down` being null + // in which case all pointers are ignored. The `_down` being null // means that _reset() has been called, since it is always set at the // first allowed down event and will not be cleared except for reset(), super.addAllowedPointer(event); diff --git a/packages/flutter/lib/src/material/button_theme.dart b/packages/flutter/lib/src/material/button_theme.dart index 4981926f409a..18d55569c1d0 100644 --- a/packages/flutter/lib/src/material/button_theme.dart +++ b/packages/flutter/lib/src/material/button_theme.dart @@ -235,7 +235,7 @@ class ButtonThemeData with Diagnosticable { /// Defaults to [ButtonBarLayoutBehavior.padded]. final ButtonBarLayoutBehavior layoutBehavior; - /// Simply a convenience that returns [minWidth] and [height] as a + /// Convenience that returns [minWidth] and [height] as a /// [BoxConstraints] object. BoxConstraints get constraints { return BoxConstraints( diff --git a/packages/flutter/lib/src/material/dropdown.dart b/packages/flutter/lib/src/material/dropdown.dart index 9becd8def0b1..0fb827634efb 100644 --- a/packages/flutter/lib/src/material/dropdown.dart +++ b/packages/flutter/lib/src/material/dropdown.dart @@ -1530,7 +1530,7 @@ class _DropdownButtonState extends State> with WidgetsBindi /// This is a convenience widget that wraps a [DropdownButton] widget in a /// [FormField]. /// -/// A [Form] ancestor is not required. The [Form] simply makes it easier to +/// A [Form] ancestor is not required. The [Form] allows one to /// save, reset, or validate multiple fields at once. To use without a [Form], /// pass a [GlobalKey] to the constructor and use [GlobalKey.currentState] to /// save or reset the form field. diff --git a/packages/flutter/lib/src/material/expansion_panel.dart b/packages/flutter/lib/src/material/expansion_panel.dart index 10a57c7e129f..8195653e8c28 100644 --- a/packages/flutter/lib/src/material/expansion_panel.dart +++ b/packages/flutter/lib/src/material/expansion_panel.dart @@ -207,14 +207,14 @@ class ExpansionPanelList extends StatefulWidget { /// is pressed. The arguments passed to the callback are the index of the /// pressed panel and whether the panel is currently expanded or not. /// - /// If ExpansionPanelList.radio is used, the callback may be called a + /// If [ExpansionPanelList.radio] is used, the callback may be called a /// second time if a different panel was previously open. The arguments /// passed to the second callback are the index of the panel that will close /// and false, marking that it will be closed. /// - /// For ExpansionPanelList, the callback needs to setState when it's notified + /// For [ExpansionPanelList], the callback needs to setState when it's notified /// about the closing/opening panel. On the other hand, the callback for - /// ExpansionPanelList.radio is simply meant to inform the parent widget of + /// [ExpansionPanelList.radio] is intended to inform the parent widget of /// changes, as the radio panels' open/close states are managed internally. /// /// This callback is useful in order to keep track of the expanded/collapsed diff --git a/packages/flutter/lib/src/material/menu_anchor.dart b/packages/flutter/lib/src/material/menu_anchor.dart index c479f8543718..2c11e9bbebdc 100644 --- a/packages/flutter/lib/src/material/menu_anchor.dart +++ b/packages/flutter/lib/src/material/menu_anchor.dart @@ -700,10 +700,10 @@ class MenuController { /// platform instead of by Flutter (on macOS, for example). /// * [ShortcutRegistry], a registry of shortcuts that apply for the entire /// application. -/// * [VoidCallbackIntent] to define intents that will call a [VoidCallback] and +/// * [VoidCallbackIntent], to define intents that will call a [VoidCallback] and /// work with the [Actions] and [Shortcuts] system. -/// * [CallbackShortcuts] to define shortcuts that simply call a callback and -/// don't involve using [Actions]. +/// * [CallbackShortcuts], to define shortcuts that call a callback without +/// involving [Actions]. class MenuBar extends StatelessWidget { /// Creates a const [MenuBar]. /// @@ -789,10 +789,10 @@ class MenuBar extends StatelessWidget { /// platform instead of by Flutter (on macOS, for example). /// * [ShortcutRegistry], a registry of shortcuts that apply for the entire /// application. -/// * [VoidCallbackIntent] to define intents that will call a [VoidCallback] and +/// * [VoidCallbackIntent], to define intents that will call a [VoidCallback] and /// work with the [Actions] and [Shortcuts] system. -/// * [CallbackShortcuts] to define shortcuts that simply call a callback and -/// don't involve using [Actions]. +/// * [CallbackShortcuts] to define shortcuts that call a callback without +/// involving [Actions]. class MenuItemButton extends StatefulWidget { /// Creates a const [MenuItemButton]. /// diff --git a/packages/flutter/lib/src/material/snack_bar.dart b/packages/flutter/lib/src/material/snack_bar.dart index 993450fbbff6..79b52bfa6816 100644 --- a/packages/flutter/lib/src/material/snack_bar.dart +++ b/packages/flutter/lib/src/material/snack_bar.dart @@ -71,8 +71,8 @@ enum SnackBarClosedReason { /// A button for a [SnackBar], known as an "action". /// -/// Snack bar actions are always enabled. If you want to disable a snack bar -/// action, simply don't include it in the snack bar. +/// Snack bar actions are always enabled. Instead of disabling a snack bar +/// action, avoid including it in the snack bar in the first place. /// /// Snack bar actions can only be pressed once. Subsequent presses are ignored. /// diff --git a/packages/flutter/lib/src/material/text_form_field.dart b/packages/flutter/lib/src/material/text_form_field.dart index a9addc22a845..a0e2e3cab379 100644 --- a/packages/flutter/lib/src/material/text_form_field.dart +++ b/packages/flutter/lib/src/material/text_form_field.dart @@ -17,7 +17,7 @@ export 'package:flutter/services.dart' show SmartDashesType, SmartQuotesType; /// This is a convenience widget that wraps a [TextField] widget in a /// [FormField]. /// -/// A [Form] ancestor is not required. The [Form] simply makes it easier to +/// A [Form] ancestor is not required. The [Form] allows one to /// save, reset, or validate multiple fields at once. To use without a [Form], /// pass a `GlobalKey` (see [GlobalKey]) to the constructor and use /// [GlobalKey.currentState] to save or reset the form field. diff --git a/packages/flutter/lib/src/painting/matrix_utils.dart b/packages/flutter/lib/src/painting/matrix_utils.dart index d7c215213224..ce259b6683ee 100644 --- a/packages/flutter/lib/src/painting/matrix_utils.dart +++ b/packages/flutter/lib/src/painting/matrix_utils.dart @@ -455,8 +455,8 @@ class MatrixUtils { /// /// The `radius` simulates the radius of the cylinder the plane is being /// wrapped onto. If the transformation is applied to a 0-dimensional dot - /// instead of a plane, the dot would simply translate by +/- `radius` pixels - /// along the `orientation` [Axis] when rotating from 0 to +/- 90 degrees. + /// instead of a plane, the dot would translate by ± `radius` pixels + /// along the `orientation` [Axis] when rotating from 0 to ±90 degrees. /// /// A positive radius means the object is closest at 0 `angle` and a negative /// radius means the object is closest at π `angle` or 180 degrees. @@ -478,7 +478,7 @@ class MatrixUtils { /// The `orientation` is the direction of the rotation axis. /// /// Because the viewing position is a point, it's never possible to see the - /// outer side of the cylinder at or past +/- π / 2 or 90 degrees and it's + /// outer side of the cylinder at or past ±π/2 or 90 degrees and it's /// almost always possible to end up seeing the inner side of the cylinder /// or the back side of the transformed plane before π / 2 when perspective > 0. static Matrix4 createCylindricalProjectionTransform({ diff --git a/packages/flutter/lib/src/rendering/box.dart b/packages/flutter/lib/src/rendering/box.dart index 7efe503b6732..08726e953b5d 100644 --- a/packages/flutter/lib/src/rendering/box.dart +++ b/packages/flutter/lib/src/rendering/box.dart @@ -1936,7 +1936,7 @@ abstract class RenderBox extends RenderObject { /// may depend on the baseline of a child (which is not available without /// doing a full layout), it may be computed by a callback about which the /// render object cannot reason, or the layout is so complex that it - /// is simply impractical to calculate the size in an efficient way. + /// is impractical to calculate the size in an efficient way. /// /// In such cases, it may be impossible (or at least impractical) to actually /// return a valid answer. In such cases, the function should call @@ -1964,7 +1964,7 @@ abstract class RenderBox extends RenderObject { /// When asserts are enabled and [debugCheckingIntrinsics] is not true, this /// method will either throw the provided [FlutterError] or it will create and /// throw a [FlutterError] with the provided `reason`. Otherwise, it will - /// simply return true. + /// return true. /// /// One of the arguments has to be provided. /// diff --git a/packages/flutter/lib/src/rendering/flow.dart b/packages/flutter/lib/src/rendering/flow.dart index b0f6d0c38ead..c186ecc4e33c 100644 --- a/packages/flutter/lib/src/rendering/flow.dart +++ b/packages/flutter/lib/src/rendering/flow.dart @@ -159,8 +159,8 @@ class FlowParentData extends ContainerBoxParentData { /// /// Rather than positioning the children during layout, the children are /// positioned using transformation matrices during the paint phase using the -/// matrices from the [FlowDelegate.paintChildren] function. The children can be -/// repositioned efficiently by simply repainting the flow. +/// matrices from the [FlowDelegate.paintChildren] function. The children are thus +/// repositioned efficiently by repainting the flow, skipping layout. /// /// The most efficient way to trigger a repaint of the flow is to supply a /// repaint argument to the constructor of the [FlowDelegate]. The flow will diff --git a/packages/flutter/lib/src/rendering/layer.dart b/packages/flutter/lib/src/rendering/layer.dart index c46b237b0cd3..0c049f78d831 100644 --- a/packages/flutter/lib/src/rendering/layer.dart +++ b/packages/flutter/lib/src/rendering/layer.dart @@ -546,7 +546,7 @@ abstract class Layer extends AbstractNode with DiagnosticableTreeMixin { /// should search for annotations, or if the layer has its own annotations to /// add. /// - /// The default implementation simply returns `false`, which means neither + /// The default implementation always returns `false`, which means neither /// the layer nor its children has annotations, and the annotation search /// is not absorbed either (see below for explanation). /// @@ -602,7 +602,7 @@ abstract class Layer extends AbstractNode with DiagnosticableTreeMixin { /// /// Returns null if no matching annotations are found. /// - /// By default this method simply calls [findAnnotations] with `onlyFirst: + /// By default this method calls [findAnnotations] with `onlyFirst: /// true` and returns the annotation of the first result. Prefer overriding /// [findAnnotations] instead of this method, because during an annotation /// search, only [findAnnotations] is recursively called, while custom @@ -628,7 +628,7 @@ abstract class Layer extends AbstractNode with DiagnosticableTreeMixin { /// /// Returns a result with empty entries if no matching annotations are found. /// - /// By default this method simply calls [findAnnotations] with `onlyFirst: + /// By default this method calls [findAnnotations] with `onlyFirst: /// false` and returns the annotations of its result. Prefer overriding /// [findAnnotations] instead of this method, because during an annotation /// search, only [findAnnotations] is recursively called, while custom diff --git a/packages/flutter/lib/src/rendering/mouse_tracker.dart b/packages/flutter/lib/src/rendering/mouse_tracker.dart index 9b9af0fa6955..75229a1d034e 100644 --- a/packages/flutter/lib/src/rendering/mouse_tracker.dart +++ b/packages/flutter/lib/src/rendering/mouse_tracker.dart @@ -302,8 +302,8 @@ class MouseTracker extends ChangeNotifier { /// [MouseTracker] filter which to react to. /// /// The `getResult` is a function to return the hit test result at the - /// position of the event. It should not simply return cached hit test - /// result, because the cache does not change throughout a tap sequence. + /// position of the event. It should not return a cached hit test + /// result, because the cache would not change during a tap sequence. void updateWithEvent(PointerEvent event, ValueGetter getResult) { if (event.kind != PointerDeviceKind.mouse) { return; diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 14ac8dbc4a29..f02efb034a20 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -24,7 +24,7 @@ export 'package:flutter/gestures.dart' show /// A base class for render boxes that resemble their children. /// -/// A proxy box has a single child and simply mimics all the properties of that +/// A proxy box has a single child and mimics all the properties of that /// child by calling through to the child for each function in the render box /// protocol. For example, a proxy box determines its size by asking its child /// to layout with the same constraints and then matching the size. @@ -41,7 +41,7 @@ export 'package:flutter/gestures.dart' show class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin, RenderProxyBoxMixin { /// Creates a proxy render box. /// - /// Proxy render boxes are rarely created directly because they simply proxy + /// Proxy render boxes are rarely created directly because they proxy /// the render box protocol to [child]. Instead, consider using one of the /// subclasses. RenderProxyBox([RenderBox? child]) { @@ -869,7 +869,7 @@ class RenderIntrinsicHeight extends RenderProxyBox { /// /// For values of opacity other than 0.0 and 1.0, this class is relatively /// expensive because it requires painting the child into an intermediate -/// buffer. For the value 0.0, the child is simply not painted at all. For the +/// buffer. For the value 0.0, the child is not painted at all. For the /// value 1.0, the child is painted immediately without an intermediate buffer. class RenderOpacity extends RenderProxyBox { /// Creates a partially transparent render object. diff --git a/packages/flutter/lib/src/rendering/proxy_sliver.dart b/packages/flutter/lib/src/rendering/proxy_sliver.dart index 519d6e539439..4ed5e22a8c2b 100644 --- a/packages/flutter/lib/src/rendering/proxy_sliver.dart +++ b/packages/flutter/lib/src/rendering/proxy_sliver.dart @@ -15,7 +15,7 @@ import 'sliver.dart'; /// A base class for sliver render objects that resemble their children. /// -/// A proxy sliver has a single child and simply mimics all the properties of +/// A proxy sliver has a single child and mimics all the properties of /// that child by calling through to the child for each function in the render /// sliver protocol. For example, a proxy sliver determines its geometry by /// asking its sliver child to layout with the same constraints and then @@ -33,7 +33,7 @@ import 'sliver.dart'; abstract class RenderProxySliver extends RenderSliver with RenderObjectWithChildMixin { /// Creates a proxy render sliver. /// - /// Proxy render slivers aren't created directly because they simply proxy + /// Proxy render slivers aren't created directly because they proxy /// the render sliver protocol to their sliver [child]. Instead, use one of /// the subclasses. RenderProxySliver([RenderSliver? child]) { @@ -94,7 +94,7 @@ abstract class RenderProxySliver extends RenderSliver with RenderObjectWithChild /// /// For values of opacity other than 0.0 and 1.0, this class is relatively /// expensive, because it requires painting the sliver child into an intermediate -/// buffer. For the value 0.0, the sliver child is simply not painted at all. +/// buffer. For the value 0.0, the sliver child is not painted at all. /// For the value 1.0, the sliver child is painted immediately without an /// intermediate buffer. class RenderSliverOpacity extends RenderProxySliver { diff --git a/packages/flutter/lib/src/rendering/sliver_multi_box_adaptor.dart b/packages/flutter/lib/src/rendering/sliver_multi_box_adaptor.dart index 99c8cd6e236a..500e1b90eef4 100644 --- a/packages/flutter/lib/src/rendering/sliver_multi_box_adaptor.dart +++ b/packages/flutter/lib/src/rendering/sliver_multi_box_adaptor.dart @@ -113,7 +113,7 @@ abstract class RenderSliverBoxChildManager { /// This function always returns true. /// /// The manager is not required to track whether it is expecting modifications - /// to the [RenderSliverMultiBoxAdaptor]'s child list and can simply return + /// to the [RenderSliverMultiBoxAdaptor]'s child list and can return /// true without making any assertions. bool debugAssertChildListLocked() => true; } diff --git a/packages/flutter/lib/src/rendering/table.dart b/packages/flutter/lib/src/rendering/table.dart index f7e340b359c4..274a749301c3 100644 --- a/packages/flutter/lib/src/rendering/table.dart +++ b/packages/flutter/lib/src/rendering/table.dart @@ -617,7 +617,7 @@ class RenderTable extends RenderBox { /// replacing the existing children. /// /// If the new cells contain any existing children of the table, those - /// children are simply moved to their new location in the table rather than + /// children are moved to their new location in the table rather than /// removed from the table and re-added. void setFlatChildren(int columns, List cells) { if (cells == _children && columns == _columns) { diff --git a/packages/flutter/lib/src/scheduler/binding.dart b/packages/flutter/lib/src/scheduler/binding.dart index 8820c7cf0412..0c107caf0c40 100644 --- a/packages/flutter/lib/src/scheduler/binding.dart +++ b/packages/flutter/lib/src/scheduler/binding.dart @@ -1275,7 +1275,7 @@ mixin SchedulerBinding on BindingBase { // Calls the given [callback] with [timestamp] as argument. // // Wraps the callback in a try/catch and forwards any error to - // [debugSchedulerExceptionHandler], if set. If not set, then simply prints + // [debugSchedulerExceptionHandler], if set. If not set, prints // the error. @pragma('vm:notify-debugger-on-exception') void _invokeFrameCallback(FrameCallback callback, Duration timeStamp, [ StackTrace? callbackStack ]) { diff --git a/packages/flutter/lib/src/semantics/semantics.dart b/packages/flutter/lib/src/semantics/semantics.dart index bed9eea8cb33..001abd19bb71 100644 --- a/packages/flutter/lib/src/semantics/semantics.dart +++ b/packages/flutter/lib/src/semantics/semantics.dart @@ -4733,7 +4733,7 @@ abstract class SemanticsSortKey with Diagnosticable implements Comparable extends Action { Object? invoke(T intent) => onInvoke(intent); } -/// An action dispatcher that simply invokes the actions given to it. +/// An action dispatcher that invokes the actions given to it. +/// +/// The [invokeAction] method on this class directly calls the [Action.invoke] +/// method on the [Action] object. +/// +/// For [ContextAction] actions, if no `context` is provided, the +/// [BuildContext] of the [primaryFocus] is used instead. /// /// See also: /// diff --git a/packages/flutter/lib/src/widgets/autocomplete.dart b/packages/flutter/lib/src/widgets/autocomplete.dart index 4e4bd957211c..0dac44443221 100644 --- a/packages/flutter/lib/src/widgets/autocomplete.dart +++ b/packages/flutter/lib/src/widgets/autocomplete.dart @@ -263,8 +263,8 @@ class RawAutocomplete extends StatefulWidget { /// The default way to convert an option to a string in /// [displayStringForOption]. /// - /// Simply uses the `toString` method on the option. - static String defaultStringForOption(dynamic option) { + /// Uses the `toString` method of the given `option`. + static String defaultStringForOption(Object? option) { return option.toString(); } diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 99179a428e53..50ffb0c0a104 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -222,7 +222,7 @@ class Directionality extends _UbiquitousInheritedWidget { /// /// For values of opacity other than 0.0 and 1.0, this class is relatively /// expensive because it requires painting the child into an intermediate -/// buffer. For the value 0.0, the child is simply not painted at all. For the +/// buffer. For the value 0.0, the child is not painted at all. For the /// value 1.0, the child is painted immediately without an intermediate buffer. /// /// The presence of the intermediate buffer which has a transparent background @@ -1896,7 +1896,7 @@ class RotatedBox extends SingleChildRenderObjectWidget { /// ### Why use a [Padding] widget rather than a [Container] with a [Container.padding] property? /// /// There isn't really any difference between the two. If you supply a -/// [Container.padding] argument, [Container] simply builds a [Padding] widget +/// [Container.padding] argument, [Container] builds a [Padding] widget /// for you. /// /// [Container] doesn't implement its properties directly. Instead, [Container] @@ -1907,7 +1907,7 @@ class RotatedBox extends SingleChildRenderObjectWidget { /// convenient, feel free to use it. If not, feel free to build these simpler /// widgets in whatever combination meets your needs. /// -/// In fact, the majority of widgets in Flutter are simply combinations of other +/// In fact, the majority of widgets in Flutter are combinations of other /// simpler widgets. Composition, rather than inheritance, is the primary /// mechanism for building up widgets. /// @@ -5439,7 +5439,7 @@ class Wrap extends MultiChildRenderObjectWidget { /// Rather than positioning the children during layout, the children are /// positioned using transformation matrices during the paint phase using the /// matrices from the [FlowDelegate.paintChildren] function. The children can be -/// repositioned efficiently by simply repainting the flow, which happens +/// repositioned efficiently by only _repainting_ the flow, which happens /// without the children being laid out again (contrast this with a [Stack], /// which does the sizing and positioning together during layout). /// @@ -6480,7 +6480,7 @@ class MouseRegion extends SingleChildRenderObjectWidget { /// Because the widget conditionally creates the `MouseRegion`, and leaks the /// hover state, it needs to take the restriction into consideration. In this /// case, since it has access to the event that triggers the disappearance of - /// the `MouseRegion`, it simply trigger the exit callback during that event + /// the `MouseRegion`, it triggers the exit callback during that event /// as well. /// /// ** See code in examples/api/lib/widgets/basic/mouse_region.on_exit.1.dart ** @@ -7373,8 +7373,8 @@ class KeyedSubtree extends StatelessWidget { /// ) /// ``` /// -/// The difference between either of the previous examples and simply -/// creating a child directly, without an intervening widget, is the +/// The difference between either of the previous examples and +/// creating a child directly without an intervening widget, is the /// extra [BuildContext] element that the additional widget adds. This /// is particularly noticeable when the tree contains an inherited /// widget that is referred to by a method like [Scaffold.of], diff --git a/packages/flutter/lib/src/widgets/focus_traversal.dart b/packages/flutter/lib/src/widgets/focus_traversal.dart index fdd94f371b30..3eb2dddaa359 100644 --- a/packages/flutter/lib/src/widgets/focus_traversal.dart +++ b/packages/flutter/lib/src/widgets/focus_traversal.dart @@ -1677,7 +1677,7 @@ class RequestFocusIntent extends Intent { /// logging, or undo and redo functionality. /// /// This [RequestFocusAction] class is the default action associated with the -/// [RequestFocusIntent] in the [WidgetsApp], and it simply requests focus. You +/// [RequestFocusIntent] in the [WidgetsApp]. It requests focus. You /// can redefine the associated action with your own [Actions] widget. /// /// See [FocusTraversalPolicy] for more information about focus traversal. diff --git a/packages/flutter/lib/src/widgets/form.dart b/packages/flutter/lib/src/widgets/form.dart index 24d4afb2ee15..749fb65d1be2 100644 --- a/packages/flutter/lib/src/widgets/form.dart +++ b/packages/flutter/lib/src/widgets/form.dart @@ -296,7 +296,7 @@ typedef FormFieldBuilder = Widget Function(FormFieldState field); /// Use a [GlobalKey] with [FormField] if you want to retrieve its current /// state, for example if you want one form field to depend on another. /// -/// A [Form] ancestor is not required. The [Form] simply makes it easier to +/// A [Form] ancestor is not required. The [Form] allows one to /// save, reset, or validate multiple fields at once. To use without a [Form], /// pass a [GlobalKey] to the constructor and use [GlobalKey.currentState] to /// save or reset the form field. diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index a1ef69e3e883..217828f6dabe 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -654,7 +654,7 @@ abstract class StatelessWidget extends Widget { /// this ideal, the more efficient it will be.) /// /// * If a subtree does not change, cache the widget that represents that -/// subtree and re-use it each time it can be used. To do this, simply assign +/// subtree and re-use it each time it can be used. To do this, assign /// a widget to a `final` state variable and re-use it in the build method. It /// is massively more efficient for a widget to be re-used than for a new (but /// identically-configured) widget to be created. Another caching strategy @@ -3841,7 +3841,7 @@ abstract class Element extends DiagnosticableTree implements BuildContext { /// Remove [renderObject] from the render tree. /// - /// The default implementation of this function simply calls + /// The default implementation of this function calls /// [detachRenderObject] recursively on each child. The /// [RenderObjectElement.detachRenderObject] override does the actual work of /// removing [renderObject] from the render tree. @@ -3856,7 +3856,7 @@ abstract class Element extends DiagnosticableTree implements BuildContext { /// Add [renderObject] to the render tree at the location specified by `newSlot`. /// - /// The default implementation of this function simply calls + /// The default implementation of this function calls /// [attachRenderObject] recursively on each child. The /// [RenderObjectElement.attachRenderObject] override does the actual work of /// adding [renderObject] to the render tree. @@ -5646,7 +5646,7 @@ class InheritedElement extends ProxyElement { /// /// However, the immediate children of the element may not be the ones that /// eventually produce the actual [RenderObject] that they correspond to. For -/// example a [StatelessElement] (the element of a [StatelessWidget]) simply +/// example, a [StatelessElement] (the element of a [StatelessWidget]) /// corresponds to whatever [RenderObject] its child (the element returned by /// its [StatelessWidget.build] method) corresponds to. /// @@ -5923,7 +5923,7 @@ abstract class RenderObjectElement extends Element { /// list after the [RenderObject] associated with the [Element] provided as /// [IndexedSlot.value] in the [slot] object. /// - /// Simply using the previous sibling as a [slot] is not enough, though, because + /// Using the previous sibling as a [slot] is not enough, though, because /// child [RenderObject]s are only moved around when the [slot] of their /// associated [RenderObjectElement]s is updated. When the order of child /// [Element]s is changed, some elements in the list may move to a new index diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart index 098634dee50c..2130e0af9e8f 100644 --- a/packages/flutter/lib/src/widgets/gesture_detector.dart +++ b/packages/flutter/lib/src/widgets/gesture_detector.dart @@ -215,11 +215,11 @@ class GestureDetector extends StatelessWidget { /// Creates a widget that detects gestures. /// /// Pan and scale callbacks cannot be used simultaneously because scale is a - /// superset of pan. Simply use the scale callbacks instead. + /// superset of pan. Use the scale callbacks instead. /// /// Horizontal and vertical drag callbacks cannot be used simultaneously - /// because a combination of a horizontal and vertical drag is a pan. Simply - /// use the pan callbacks instead. + /// because a combination of a horizontal and vertical drag is a pan. + /// Use the pan callbacks instead. /// /// {@youtube 560 315 https://www.youtube.com/watch?v=WhVXkCFPmK4} /// diff --git a/packages/flutter/lib/src/widgets/icon_theme_data.dart b/packages/flutter/lib/src/widgets/icon_theme_data.dart index 9a2cc5d34dc7..d61d39febd08 100644 --- a/packages/flutter/lib/src/widgets/icon_theme_data.dart +++ b/packages/flutter/lib/src/widgets/icon_theme_data.dart @@ -76,7 +76,7 @@ class IconThemeData with Diagnosticable { /// Returns a new icon theme that matches this icon theme but with some values /// replaced by the non-null parameters of the given icon theme. If the given - /// icon theme is null, simply returns this icon theme. + /// icon theme is null, returns this icon theme. IconThemeData merge(IconThemeData? other) { if (other == null) { return this; diff --git a/packages/flutter/lib/src/widgets/interactive_viewer.dart b/packages/flutter/lib/src/widgets/interactive_viewer.dart index 832bdcd09566..005bb991609e 100644 --- a/packages/flutter/lib/src/widgets/interactive_viewer.dart +++ b/packages/flutter/lib/src/widgets/interactive_viewer.dart @@ -1141,7 +1141,7 @@ class _InteractiveViewerState extends State with TickerProvid } } -// This widget simply allows us to easily swap in and out the LayoutBuilder in +// This widget allows us to easily swap in and out the LayoutBuilder in // InteractiveViewer's depending on if it's using a builder or a child. class _InteractiveViewerBuilt extends StatelessWidget { const _InteractiveViewerBuilt({ diff --git a/packages/flutter/lib/src/widgets/navigator.dart b/packages/flutter/lib/src/widgets/navigator.dart index 3d0979f313e8..2fe21397ad2d 100644 --- a/packages/flutter/lib/src/widgets/navigator.dart +++ b/packages/flutter/lib/src/widgets/navigator.dart @@ -611,15 +611,15 @@ class NavigatorObserver { /// The navigator that the observer is observing, if any. NavigatorState? get navigator => _navigators[this]; - /// Expando mapping instances of NavigatorObserver to their associated - /// NavigatorState (or `null`, if there is no associated NavigatorState). The - /// reason we don't simply use a private instance field of type - /// `NavigatorState?` is because as part of implementing - /// https://github.com/dart-lang/language/issues/2020, it will soon become a - /// runtime error to invoke a private member that is mocked in another - /// library. By using an expando rather than an instance field, we ensure - /// that a mocked NavigatorObserver can still properly keep track of its - /// associated NavigatorState. + // Expando mapping instances of NavigatorObserver to their associated + // NavigatorState (or `null`, if there is no associated NavigatorState). The + // reason we don't use a private instance field of type + // `NavigatorState?` is because as part of implementing + // https://github.com/dart-lang/language/issues/2020, it will soon become a + // runtime error to invoke a private member that is mocked in another + // library. By using an expando rather than an instance field, we ensure + // that a mocked NavigatorObserver can still properly keep track of its + // associated NavigatorState. static final Expando _navigators = Expando(); /// The [Navigator] pushed `route`. diff --git a/packages/flutter/lib/src/widgets/orientation_builder.dart b/packages/flutter/lib/src/widgets/orientation_builder.dart index 189a621c580e..3bed33422fb9 100644 --- a/packages/flutter/lib/src/widgets/orientation_builder.dart +++ b/packages/flutter/lib/src/widgets/orientation_builder.dart @@ -35,7 +35,7 @@ class OrientationBuilder extends StatelessWidget { /// Builds the widgets below this widget given this widget's orientation. /// - /// A widget's orientation is simply a factor of its width relative to its + /// A widget's orientation is a factor of its width relative to its /// height. For example, a [Column] widget will have a landscape orientation /// if its width exceeds its height, even though it displays its children in /// a vertical array. diff --git a/packages/flutter/lib/src/widgets/overlay.dart b/packages/flutter/lib/src/widgets/overlay.dart index 58e52eb56833..15a5fe2aa437 100644 --- a/packages/flutter/lib/src/widgets/overlay.dart +++ b/packages/flutter/lib/src/widgets/overlay.dart @@ -280,7 +280,7 @@ class _OverlayEntryWidgetState extends State<_OverlayEntryWidget> { /// The [Overlay] widget uses a custom stack implementation, which is very /// similar to the [Stack] widget. The main use case of [Overlay] is related to /// navigation and being able to insert widgets on top of the pages in an app. -/// To simply display a stack of widgets, consider using [Stack] instead. +/// For layout purposes unrelated to navigation, consider using [Stack] instead. /// /// An [Overlay] widget requires a [Directionality] widget to be in scope, so /// that it can resolve direction-sensitive coordinates of any diff --git a/packages/flutter/lib/src/widgets/platform_menu_bar.dart b/packages/flutter/lib/src/widgets/platform_menu_bar.dart index b670c96000ae..c4840176b704 100644 --- a/packages/flutter/lib/src/widgets/platform_menu_bar.dart +++ b/packages/flutter/lib/src/widgets/platform_menu_bar.dart @@ -954,7 +954,7 @@ enum PlatformProvidedMenuItemType { /// /// On macOS, this is the `terminate` default menu. /// - /// This menu item will simply exit the application when activated. + /// This menu item will exit the application when activated. quit, /// The system provided "Services" submenu. diff --git a/packages/flutter/lib/src/widgets/scroll_physics.dart b/packages/flutter/lib/src/widgets/scroll_physics.dart index 0d7db82e1d86..d4519035104d 100644 --- a/packages/flutter/lib/src/widgets/scroll_physics.dart +++ b/packages/flutter/lib/src/widgets/scroll_physics.dart @@ -236,8 +236,8 @@ class ScrollPhysics { /// the overall scale between the global screen and local scrollable /// coordinate systems. /// - /// The default implementation is stateless, and simply provides a point-in- - /// time decision about how fast the scrollable is scrolling. It would always + /// The default implementation is stateless, and provides a point-in-time + /// decision about how fast the scrollable is scrolling. It would always /// return true for a scrollable that is animating back and forth at high /// velocity in a loop. It is assumed that callers will handle such /// a case, or that a custom stateful implementation would be written that diff --git a/packages/flutter/lib/src/widgets/single_child_scroll_view.dart b/packages/flutter/lib/src/widgets/single_child_scroll_view.dart index d2361d723ab3..b8a7835b6f6d 100644 --- a/packages/flutter/lib/src/widgets/single_child_scroll_view.dart +++ b/packages/flutter/lib/src/widgets/single_child_scroll_view.dart @@ -48,17 +48,18 @@ import 'scrollable.dart'; /// small window in split-screen mode. In any case, as a result, it might /// make sense to wrap the layout in a [SingleChildScrollView]. /// -/// Simply doing so, however, usually results in a conflict between the [Column], +/// Doing so, however, usually results in a conflict between the [Column], /// which typically tries to grow as big as it can, and the [SingleChildScrollView], /// which provides its children with an infinite amount of space. /// /// To resolve this apparent conflict, there are a couple of techniques, as /// discussed below. These techniques should only be used when the content is -/// normally expected to fit on the screen, so that the lazy instantiation of -/// a sliver-based [ListView] or [CustomScrollView] is not expected to provide -/// any performance benefit. If the viewport is expected to usually contain -/// content beyond the dimensions of the screen, then [SingleChildScrollView] -/// would be very expensive. +/// normally expected to fit on the screen, so that the lazy instantiation of a +/// sliver-based [ListView] or [CustomScrollView] is not expected to provide any +/// performance benefit. If the viewport is expected to usually contain content +/// beyond the dimensions of the screen, then [SingleChildScrollView] would be +/// very expensive (in which case [ListView] may be a better choice than +/// [Column]). /// /// ### Centering, spacing, or aligning fixed-height content /// diff --git a/packages/flutter/lib/src/widgets/sliver.dart b/packages/flutter/lib/src/widgets/sliver.dart index aac5de39243f..5dce14a15900 100644 --- a/packages/flutter/lib/src/widgets/sliver.dart +++ b/packages/flutter/lib/src/widgets/sliver.dart @@ -417,7 +417,7 @@ class SliverChildBuilderDelegate extends SliverChildDelegate { /// boundaries so that they do not need to be repainted as the list scrolls. /// If the children are easy to repaint (e.g., solid color blocks or a short /// snippet of text), it might be more efficient to not add a repaint boundary - /// and simply repaint the children during scrolling. + /// and instead always repaint the children during scrolling. /// /// Defaults to true. final bool addRepaintBoundaries; @@ -632,7 +632,7 @@ class SliverChildListDelegate extends SliverChildDelegate { /// boundaries so that they do not need to be repainted as the list scrolls. /// If the children are easy to repaint (e.g., solid color blocks or a short /// snippet of text), it might be more efficient to not add a repaint boundary - /// and simply repaint the children during scrolling. + /// and instead always repaint the children during scrolling. /// /// Defaults to true. final bool addRepaintBoundaries; @@ -1681,7 +1681,7 @@ class SliverMultiBoxAdaptorElement extends RenderObjectElement implements Render /// /// For values of opacity other than 0.0 and 1.0, this class is relatively /// expensive because it requires painting the sliver child into an intermediate -/// buffer. For the value 0.0, the sliver child is simply not painted at all. +/// buffer. For the value 0.0, the sliver child is not painted at all. /// For the value 1.0, the sliver child is painted immediately without an /// intermediate buffer. /// diff --git a/packages/flutter/lib/src/widgets/text_selection.dart b/packages/flutter/lib/src/widgets/text_selection.dart index 211036cf8009..733c2e287c07 100644 --- a/packages/flutter/lib/src/widgets/text_selection.dart +++ b/packages/flutter/lib/src/widgets/text_selection.dart @@ -2512,7 +2512,7 @@ class TextSelectionGestureDetectorBuilder { /// Handler for [TextSelectionGestureDetector.onDragSelectionEnd]. /// - /// By default, it simply cleans up the state used for handling certain + /// By default, it cleans up the state used for handling certain /// built-in behaviors. /// /// See also: diff --git a/packages/flutter/lib/src/widgets/transitions.dart b/packages/flutter/lib/src/widgets/transitions.dart index ce9ba3fc8d3f..4f666d158138 100644 --- a/packages/flutter/lib/src/widgets/transitions.dart +++ b/packages/flutter/lib/src/widgets/transitions.dart @@ -22,7 +22,7 @@ export 'package:flutter/rendering.dart' show RelativeRect; /// [ChangeNotifier] and [ValueNotifier]. /// /// [AnimatedWidget] is most useful for widgets that are otherwise stateless. To -/// use [AnimatedWidget], simply subclass it and implement the build function. +/// use [AnimatedWidget], subclass it and implement the build function. /// /// {@tool dartpad} /// This code defines a widget called `Spinner` that spins a green square @@ -1003,7 +1003,7 @@ class DefaultTextStyleTransition extends AnimatedWidget { /// /// [ListenableBuilder] is useful for more complex widgets that wish to listen /// to changes in other objects as part of a larger build function. To use -/// [ListenableBuilder], simply construct the widget and pass it a [builder] +/// [ListenableBuilder], construct the widget and pass it a [builder] /// function. /// /// Any subtype of [Listenable] (such as a [ChangeNotifier], [ValueNotifier], or @@ -1100,7 +1100,7 @@ class ListenableBuilder extends AnimatedWidget { /// /// [AnimatedBuilder] is useful for more complex widgets that wish to include /// an animation as part of a larger build function. To use [AnimatedBuilder], -/// simply construct the widget and pass it a builder function. +/// construct the widget and pass it a builder function. /// /// For simple cases without additional state, consider using /// [AnimatedWidget]. diff --git a/packages/flutter/lib/src/widgets/value_listenable_builder.dart b/packages/flutter/lib/src/widgets/value_listenable_builder.dart index 76cd9879288d..dc4a9bc76142 100644 --- a/packages/flutter/lib/src/widgets/value_listenable_builder.dart +++ b/packages/flutter/lib/src/widgets/value_listenable_builder.dart @@ -141,10 +141,11 @@ class ValueListenableBuilder extends StatefulWidget { /// A [valueListenable]-independent widget which is passed back to the [builder]. /// - /// This argument is optional and can be null if the entire widget subtree - /// the [builder] builds depends on the value of the [valueListenable]. For - /// example, if the [valueListenable] is a [String] and the [builder] simply - /// returns a [Text] widget with the [String] value. + /// This argument is optional and can be null if the entire widget subtree the + /// [builder] builds depends on the value of the [valueListenable]. For + /// example, in the case where the [valueListenable] is a [String] and the + /// [builder] returns a [Text] widget with the current [String] value, there + /// would be no useful [child]. final Widget? child; @override diff --git a/packages/flutter_tools/lib/src/base/deferred_component.dart b/packages/flutter_tools/lib/src/base/deferred_component.dart index dda7d9c9e9ae..1d0ad93f3aef 100644 --- a/packages/flutter_tools/lib/src/base/deferred_component.dart +++ b/packages/flutter_tools/lib/src/base/deferred_component.dart @@ -50,7 +50,7 @@ class DeferredComponent { /// Indicates if the component has loading units assigned. /// - /// Unassigned components simply reflect the pubspec.yaml configuration directly, + /// Unassigned components reflect the pubspec.yaml configuration directly, /// contain no loading unit data, and [loadingUnits] is null. Once assigned, the component /// will contain a set of [loadingUnits] which contains the [LoadingUnit]s that the /// component needs to include. Loading units can be assigned with the [assignLoadingUnits] diff --git a/packages/flutter_tools/lib/src/base/utils.dart b/packages/flutter_tools/lib/src/base/utils.dart index 142b801f07cb..9a437c85ba0e 100644 --- a/packages/flutter_tools/lib/src/base/utils.dart +++ b/packages/flutter_tools/lib/src/base/utils.dart @@ -288,7 +288,7 @@ class _AnsiRun { /// widths is fine, for instance). /// /// If [outputPreferences.wrapText] is false, then the text will be returned -/// simply split at the newlines, but not wrapped. If [shouldWrap] is specified, +/// split at the newlines, but not wrapped. If [shouldWrap] is specified, /// then it overrides the [outputPreferences.wrapText] setting. List _wrapTextAsLines(String text, { int start = 0, diff --git a/packages/flutter_tools/lib/src/localizations/localizations_utils.dart b/packages/flutter_tools/lib/src/localizations/localizations_utils.dart index c8e29d21b507..cd4f9e28bc48 100644 --- a/packages/flutter_tools/lib/src/localizations/localizations_utils.dart +++ b/packages/flutter_tools/lib/src/localizations/localizations_utils.dart @@ -297,7 +297,8 @@ String generateString(String value) { /// Given a list of strings, placeholders, or helper function calls, concatenate /// them into one expression to be returned. -/// If isSingleStringVar is passed, then we want to convert "'$expr'" to simply "expr". +/// +/// If `isSingleStringVar` is passed, then we want to convert "'$expr'" to "expr". String generateReturnExpr(List expressions, { bool isSingleStringVar = false }) { if (expressions.isEmpty) { return "''"; diff --git a/packages/flutter_tools/test/integration.shard/test_data/gen_l10n_project.dart b/packages/flutter_tools/test/integration.shard/test_data/gen_l10n_project.dart index 13639aa3efb5..b3c55ab71b92 100644 --- a/packages/flutter_tools/test/integration.shard/test_data/gen_l10n_project.dart +++ b/packages/flutter_tools/test/integration.shard/test_data/gen_l10n_project.dart @@ -700,9 +700,9 @@ void main() { } '''; - /// All messages are simply the template language's message with 'ES - ' - /// appended. This makes validating test behavior easier. The interpolated - /// messages are different where applicable. + // All these messages are the template language's message with 'ES - ' + // appended. This makes validating test behavior easier. The interpolated + // messages are different where applicable. final String appEs = r''' { "@@locale": "es",