Taboo the word "simply" from our API documentation. (#116061)

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.
+// Measures the performance of image decoding.
-///
+//
-/// The benchmark measures the decoding latency and not impact on jank. It
+// The benchmark measures the decoding latency and not impact on jank. It
-/// cannot distinguish between blocking and non-blocking decoding. It simply
+// cannot distinguish between blocking and non-blocking decoding. It naively
-/// measures the total time it takes to decode image frames. For example, the
+// 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,
+// 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
+// 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.
+// and does not jank. However, the benchmark result may be the same.
-///
+//
-/// This benchmark does not support the HTML renderer because the HTML renderer
+// This benchmark does not support the HTML renderer because the HTML renderer
-/// cannot decode image frames (it always returns 1 dummy frame, even for
+// cannot decode image frames (it always returns 1 dummy frame, even for
-/// animated images).
+// animated images).
 class BenchImageDecoding extends RawRecorder {
   BenchImageDecoding() : super(
     name: benchmarkName,

dev/bots/analyze.dart

@@ -143,6 +143,9 @@ Future<void> run(List<String> 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, <String>['update-packages', '--verify-only'],
@@ -1815,18 +1818,17 @@ Future<void> verifyNullInitializedDebugExpensiveFields(String workingDirectory,
   final List<String> errors = <String>[];
   for (final File file in files) {
     final List<String> lines = file.readAsLinesSync();
-    for (int i = 0; i < lines.length; i += 1) {
+    for (int index = 0; index < lines.length; index += 1) {
-      final String line = lines[i];
+      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(<String>[
      '${bold}ERROR: ${red}fields annotated with @_debugOnly must null initialize.$reset',
@@ -1839,6 +1841,29 @@ Future<void> verifyNullInitializedDebugExpensiveFields(String workingDirectory,
   }
 }
 
+final RegExp tabooPattern = RegExp(r'^ *///.*\b(simply)\b', caseSensitive: false);
+
+Future<void> verifyTabooDocumentation(String workingDirectory, { int minimumMatches = 100 }) async {
+  final List<String> errors = <String>[];
+  await for (final File file in _allFiles(workingDirectory, 'dart', minimumMatches: minimumMatches)) {
+    final List<String> 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(<String>[
+      '${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<CommandResult> _runFlutterAnalyze(String workingDirectory, {
   List<String> options = const <String>[],
 }) async {

dev/bots/test/analyze-test-input/root/packages/flutter/lib/bar.dart

@@ -16,3 +16,6 @@ class Foo {
   @_debugOnly
   final Map<String, String>? bar = kDebugMode ? null : <String, String>{};
 }
+
+/// Simply avoid this
+/// and simply do that.

dev/bots/test/analyze_test.dart

@@ -176,7 +176,18 @@ void main() {
       minimumMatches: 1,
     ), shouldHaveErrors: true);
 
-    expect(result, contains('L15'));
+    expect(result, contains(':15'));
-    expect(result, isNot(contains('L12')));
+    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'));
   });
 }

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

@@ -255,8 +255,8 @@ class ProxyAnimation extends Animation<double>
 /// 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
+/// 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
+/// `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:

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
+/// When closed, the [CupertinoContextMenu] displays the child as if the
-/// CupertinoContextMenu were not there. Sizing and positioning is unaffected.
+/// [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.
+/// This sample shows a very simple [CupertinoContextMenu] for the Flutter logo.
-/// Simply long press on it to open.
+/// 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
+  /// This builder can be used instead of the child when the intended child has
-  /// child has a property that would conflict with the default animation, like
+  /// a property that would conflict with the default animation, such as a
-  /// a border radius or a shadow, or if simply a more custom animation is
+  /// border radius or a shadow, or if a more custom animation is needed.
-  /// needed.
   ///
   /// In addition to the current [BuildContext], the function is also called
   /// with an [Animation]. The complete animation goes from 0 to 1 when

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}

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.

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;
 

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);

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(

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

@@ -1530,7 +1530,7 @@ class _DropdownButtonState<T> extends State<DropdownButton<T>> 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.

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

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
+/// * [CallbackShortcuts], to define shortcuts that call a callback without
-///   don't involve using [Actions].
+///   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
+/// * [CallbackShortcuts] to define shortcuts that call a callback without
-///   don't involve using [Actions].
+///   involving [Actions].
 class MenuItemButton extends StatefulWidget {
   /// Creates a const [MenuItemButton].
   ///

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
+/// Snack bar actions are always enabled. Instead of disabling a snack bar
-/// action, simply don't include it in the 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.
 ///

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<FormFieldState>` (see [GlobalKey]) to the constructor and use
 /// [GlobalKey.currentState] to save or reset the form field.

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
+  /// instead of a plane, the dot would translate by ± `radius` pixels
-  /// along the `orientation` [Axis] when rotating from 0 to +/- 90 degrees.
+  /// 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({

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.
   ///

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

@@ -159,8 +159,8 @@ class FlowParentData extends ContainerBoxParentData<RenderBox> {
 ///
 /// 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
+/// matrices from the [FlowDelegate.paintChildren] function. The children are thus
-/// repositioned efficiently by simply repainting the flow.
+/// 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

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

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
+  /// position of the event. It should not return a cached hit test
-  /// result, because the cache does not change throughout a tap sequence.
+  /// result, because the cache would not change during a tap sequence.
   void updateWithEvent(PointerEvent event, ValueGetter<HitTestResult> getResult) {
     if (event.kind != PointerDeviceKind.mouse) {
       return;

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<RenderBox>, RenderProxyBoxMixin<RenderBox> {
   /// 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.

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<RenderSliver> {
   /// 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 {

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;
 }

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<RenderBox?> cells) {
     if (cells == _children && columns == _columns) {

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 ]) {

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

@@ -4733,7 +4733,7 @@ abstract class SemanticsSortKey with Diagnosticable implements Comparable<Semant
   }
 }
 
-/// A [SemanticsSortKey] that sorts simply based on the `double` value it is
+/// A [SemanticsSortKey] that sorts based on the `double` value it is
 /// given.
 ///
 /// The [OrdinalSortKey] compares itself with other [OrdinalSortKey]s

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

@@ -115,10 +115,10 @@ abstract class KeyEvent with Diagnosticable {
   ///
   /// Also, even though physical keys are defined with USB HID codes, their
   /// values are not necessarily the same HID codes produced by the hardware and
-  /// presented to the driver, because on most platforms Flutter has to map the
+  /// presented to the driver. On most platforms, Flutter has to map the
-  /// platform representation back to an HID code since the original HID
+  /// platform representation back to a HID code because the original HID
-  /// code is not provided. USB HID is simply a conveniently well-defined
+  /// code is not provided. USB HID was chosen because it is a well-defined
-  /// standard to list possible keys that a Flutter app can encounter.
+  /// standard for referring to keys such as those a Flutter app may encounter.
   ///
   /// See also:
   ///

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

@@ -541,7 +541,13 @@ class CallbackAction<T extends Intent> extends Action<T> {
   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:
 ///

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

@@ -263,8 +263,8 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
   /// The default way to convert an option to a string in
   /// [displayStringForOption].
   ///
-  /// Simply uses the `toString` method on the option.
+  /// Uses the `toString` method of the given `option`.
-  static String defaultStringForOption(dynamic option) {
+  static String defaultStringForOption(Object? option) {
     return option.toString();
   }
 

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
+/// The difference between either of the previous examples and
-/// creating a child directly, without an intervening widget, is the
+/// 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],

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.

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

@@ -296,7 +296,7 @@ typedef FormFieldBuilder<T> = Widget Function(FormFieldState<T> 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.

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

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
+  /// because a combination of a horizontal and vertical drag is a pan.
-  /// use the pan callbacks instead.
+  /// Use the pan callbacks instead.
   ///
   /// {@youtube 560 315 https://www.youtube.com/watch?v=WhVXkCFPmK4}
   ///

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;

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

@@ -1141,7 +1141,7 @@ class _InteractiveViewerState extends State<InteractiveViewer> 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({

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
+  // Expando mapping instances of NavigatorObserver to their associated
-  /// NavigatorState (or `null`, if there is no associated NavigatorState). The
+  // NavigatorState (or `null`, if there is no associated NavigatorState). The
-  /// reason we don't simply use a private instance field of type
+  // reason we don't use a private instance field of type
-  /// `NavigatorState?` is because as part of implementing
+  // `NavigatorState?` is because as part of implementing
-  /// https://github.com/dart-lang/language/issues/2020, it will soon become a
+  // 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
+  // runtime error to invoke a private member that is mocked in another
-  /// library. By using an expando rather than an instance field, we ensure
+  // library. By using an expando rather than an instance field, we ensure
-  /// that a mocked NavigatorObserver can still properly keep track of its
+  // that a mocked NavigatorObserver can still properly keep track of its
-  /// associated NavigatorState.
+  // associated NavigatorState.
   static final Expando<NavigatorState> _navigators = Expando<NavigatorState>();
 
   /// The [Navigator] pushed `route`.

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.

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

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.

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-
+  /// The default implementation is stateless, and provides a point-in-time
-  /// time decision about how fast the scrollable is scrolling. It would always
+  /// 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

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
+/// normally expected to fit on the screen, so that the lazy instantiation of a
-/// a sliver-based [ListView] or [CustomScrollView] is not expected to provide
+/// sliver-based [ListView] or [CustomScrollView] is not expected to provide any
-/// any performance benefit. If the viewport is expected to usually contain
+/// performance benefit. If the viewport is expected to usually contain content
-/// content beyond the dimensions of the screen, then [SingleChildScrollView]
+/// beyond the dimensions of the screen, then [SingleChildScrollView] would be
-/// would be very expensive.
+/// very expensive (in which case [ListView] may be a better choice than
+/// [Column]).
 ///
 /// ### Centering, spacing, or aligning fixed-height content
 ///

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.
 ///

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:

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].

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

@@ -141,10 +141,11 @@ class ValueListenableBuilder<T> 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
+  /// This argument is optional and can be null if the entire widget subtree the
-  /// the [builder] builds depends on the value of the [valueListenable]. For
+  /// [builder] builds depends on the value of the [valueListenable]. For
-  /// example, if the [valueListenable] is a [String] and the [builder] simply
+  /// example, in the case where the [valueListenable] is a [String] and the
-  /// returns a [Text] widget with the [String] value.
+  /// [builder] returns a [Text] widget with the current [String] value, there
+  /// would be no useful [child].
   final Widget? child;
 
   @override

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]

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<String> _wrapTextAsLines(String text, {
   int start = 0,

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<String> expressions, { bool isSingleStringVar = false }) {
   if (expressions.isEmpty) {
     return "''";

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 - '
+  // All these messages are the template language's message with 'ES - '
-  /// appended. This makes validating test behavior easier. The interpolated
+  // appended. This makes validating test behavior easier. The interpolated
-  /// messages are different where applicable.
+  // messages are different where applicable.
   final String appEs = r'''
 {
   "@@locale": "es",