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

Author: Hixie

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,

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) {
-      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(<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, 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'));
   });
 }

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

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

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