Remove "note that" in our documentation (as per style guide) (#120842)

* lerp documentation

* Remove Note, Note That from repo

* Improve BorderSide documentation.

* apply review comments

dev/benchmarks/complex_layout/lib/src/app.dart

@@ -630,7 +630,7 @@ class GalleryDrawer extends StatelessWidget {
   Widget build(BuildContext context) {
     final ScrollMode currentMode = ComplexLayoutApp.of(context)!.scrollMode;
     return Drawer(
-      // Note: for real apps, see the Gallery material Drawer demo. More
+      // For real apps, see the Gallery material Drawer demo. More
       // typically, a drawer would have a fixed header with a scrolling body
       // below it.
       child: ListView(

dev/benchmarks/microbenchmarks/lib/foundation/platform_asset_bundle.dart

@@ -24,7 +24,7 @@ void main() async {
     watch.reset();
     watch.start();
     for (int i = 0; i < _kBatchSize; i += 1) {
-      // Note: We don't load images like this. PlatformAssetBundle is used for
+      // We don't load images like this. PlatformAssetBundle is used for
       // other assets (like Rive animations). We are using an image because it's
       // conveniently sized and available for the test.
       tally += (await bundle.load('packages/flutter_gallery_assets/places/india_pondicherry_salt_farm.png')).lengthInBytes;

dev/benchmarks/multiple_flutters/android/build.gradle

@@ -13,8 +13,8 @@ buildscript {
         classpath "com.android.tools.build:gradle:7.3.0"
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
 
-        // NOTE: Do not place your application dependencies here; they belong
+        // Do not place your application dependencies here; they belong
-        // in the individual module build.gradle files
+        // in the individual module build.gradle files.
     }
 }
 

dev/bots/analyze.dart

@@ -1842,7 +1842,7 @@ Future<void> verifyNullInitializedDebugExpensiveFields(String workingDirectory,
   }
 }
 
-final RegExp tabooPattern = RegExp(r'^ *///.*\b(simply)\b', caseSensitive: false);
+final RegExp tabooPattern = RegExp(r'^ *///.*\b(simply|note:|note that)\b', caseSensitive: false);
 
 Future<void> verifyTabooDocumentation(String workingDirectory, { int minimumMatches = 100 }) async {
   final List<String> errors = <String>[];
@@ -1859,7 +1859,8 @@ Future<void> verifyTabooDocumentation(String workingDirectory, { int minimumMatc
   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',
+      '${bold}In many cases thes words 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',
+      '${bold}Similarly, avoid using "note:" or the phrase "note that". See https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#avoid-empty-prose for details.$reset',
       ...errors,
     ]);
   }

dev/bots/docs.sh

@@ -18,7 +18,7 @@ function script_location() {
 
 function generate_docs() {
     # Install and activate dartdoc.
-    # NOTE: When updating to a new dartdoc version, please also update
+    # When updating to a new dartdoc version, please also update
     # `dartdoc_options.yaml` to include newly introduced error and warning types.
     "$DART" pub global activate dartdoc 6.1.5
 

dev/ci/README.md

@@ -9,7 +9,7 @@ On each new change to this `Dockerfile`, Cirrus will build a new version of
 the Docker image as a dependency to any Linux tests. It is no longer necessary
 to manually build and push the Docker image locally.
 
-NOTE: there are some factors external to the actual `Dockerfile` that would
+There are some factors external to the actual `Dockerfile` that would
 necessitate rebuilding the Docker image, such as upstream code changes, (Linux
 distribution) repository updates or a file that gets `COPY`ied into the image
 changing. In this case, a trivial `Dockerfile` change (such as a comment)

dev/conductor/core/lib/src/repository.dart

@@ -129,8 +129,7 @@ abstract class Repository {
           'Fetch ${upstreamRemote.name} to ensure we have latest refs',
           workingDirectory: _checkoutDirectory!.path,
         );
-        // Note: if [initialRef] is a remote ref the checkout will be left in a
+        // If [initialRef] is a remote ref, the checkout will be left in a detached HEAD state.
-        // detached HEAD state.
         await git.run(
           <String>['checkout', initialRef!],
           'Checking out initialRef $initialRef',

dev/conductor/core/test/start_test.dart

@@ -531,7 +531,7 @@ void main() {
           '171876a4e6cf56ee6da1f97d203926bd7afda7ef';
       const String nextDartRevision =
           'f6c91128be6b77aef8351e1e3a9d07c85bc2e46e';
-      // note that this significantly behind the candidate branch name
+      // This is significantly behind the candidate branch name
       const String previousVersion = '0.9.0-1.0.pre';
       // This is what this release will be
       const String nextVersion = '0.9.0-1.1.pre';

dev/integration_tests/flutter_gallery/lib/gallery/example_code.dart

@@ -2,8 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// Note: This code is not runnable, it contains code snippets displayed in the
+// This code is not runnable, it contains code snippets displayed in the Gallery.
-// gallery.
 
 import 'package:flutter/material.dart';
 

dev/integration_tests/ios_add2app_life_cycle/ios_add2app/FullScreenViewController.m

@@ -22,9 +22,9 @@
   self.navigationController.navigationBarHidden = NO;
   self.navigationController.hidesBarsOnSwipe = NO;
   if (self.isMovingFromParentViewController) {
-    // Note that if we were doing things that might cause the VC
+    // If we were doing things that might cause the VC
     // to disappear (like using the image_picker plugin)
-    // we shouldn't do this.  But in this case we know we're
+    // we shouldn't do this, but in this case we know we're
     // just going back to the navigation controller.
     // If we needed Flutter to tell us when we could actually go away,
     // we'd need to communicate over a method channel with it.

dev/integration_tests/ios_host_app/Host/FullScreenViewController.m

@@ -22,9 +22,9 @@
   self.navigationController.navigationBarHidden = NO;
   self.navigationController.hidesBarsOnSwipe = NO;
   if (self.isMovingFromParentViewController) {
-    // Note that if we were doing things that might cause the VC
+    // If we were doing things that might cause the VC
     // to disappear (like using the image_picker plugin)
-    // we shouldn't do this.  But in this case we know we're
+    // we shouldn't do this, but in this case we know we're
     // just going back to the navigation controller.
     // If we needed Flutter to tell us when we could actually go away,
     // we'd need to communicate over a method channel with it.

dev/integration_tests/ios_host_app/flutterapp/lib/main

@@ -21,9 +21,9 @@ const String hybridRouteName = 'hybrid';
 /// Channel used to let the Flutter app know to reset the app to a specific
 /// route.  See the [run] method.
 ///
-/// Note that we shouldn't use the `setInitialRoute` method on the system
+/// We shouldn't use the `setInitialRoute` method on the system
-/// navigation channel, as that never gets propagated back to Flutter after the
+/// navigation channel, as that never gets propagated back to Flutter
-/// initial call.
+/// after the initial call.
 const String _kReloadChannelName = 'reload';
 const BasicMessageChannel<String> _kReloadChannel =
     BasicMessageChannel<String>(_kReloadChannelName, StringCodec());

dev/tools/gen_keycodes/lib/physical_key_data.dart

@@ -76,18 +76,21 @@ class PhysicalKeyData {
     return outputMap;
   }
 
-  /// Parses entries from Androids Generic.kl scan code data file.
+  /// Parses entries from Android's `Generic.kl` scan code data file.
   ///
   /// Lines in this file look like this (without the ///):
+  ///
+  /// ```
   /// key 100   ALT_RIGHT
   /// # key 101 "KEY_LINEFEED"
   /// key 477   F12               FUNCTION
+  /// ```
   ///
   /// We parse the commented out lines as well as the non-commented lines, so
   /// that we can get names for all of the available scan codes, not just ones
   /// defined for the generic profile.
   ///
-  /// Also, note that some keys (notably MEDIA_EJECT) can be mapped to more than
+  /// Some keys (notably `MEDIA_EJECT`) can be mapped to more than
   /// one scan code, so the mapping can't just be 1:1, it has to be 1:many.
   static Map<String, List<int>> _readAndroidScanCodes(String keyboardLayout, String nameMap) {
     final RegExp keyEntry = RegExp(

examples/api/lib/widgets/focus_traversal/focus_traversal_group.0.dart

@@ -164,7 +164,7 @@ class MyStatelessWidget extends StatelessWidget {
             ),
             // A group that orders in widget order, regardless of what the order is set to.
             FocusTraversalGroup(
-              // Note that because this is NOT an OrderedTraversalPolicy, the
+              // Because this is NOT an OrderedTraversalPolicy, the
               // assigned order of these OrderedButtons is ignored, and they
               // are traversed in widget order. TRY THIS: change this to
               // "OrderedTraversalPolicy()" and see that it now follows the

examples/api/lib/widgets/shared_app_data/shared_app_data.0.dart

@@ -52,7 +52,7 @@ class _HomeState extends State<Home> {
                 _fooVersion += 1;
                 // Changing the SharedAppData's value for 'foo' causes the
                 // widgets that depend on 'foo' to be rebuilt.
-                SharedAppData.setValue<String, String?>(context, 'foo', 'FOO $_fooVersion'); // note: no setState()
+                SharedAppData.setValue<String, String?>(context, 'foo', 'FOO $_fooVersion'); // no need to call setState()
               },
             ),
             const SizedBox(height: 16),
@@ -60,7 +60,7 @@ class _HomeState extends State<Home> {
               child: const Text('change bar'),
               onPressed: () {
                 _barVersion += 1;
-                SharedAppData.setValue<String, String?>(context, 'bar', 'BAR $_barVersion');  // note: no setState()
+                SharedAppData.setValue<String, String?>(context, 'bar', 'BAR $_barVersion');  // no need to call setState()
               },
             ),
           ],

examples/api/test/widgets/gesture_detector/gesture_detector.2_test.dart

@@ -28,7 +28,7 @@ void main() {
   }
 
   void expectInnerGestureDetectorBehavior(WidgetTester tester, HitTestBehavior behavior) {
-    // Note that there is a third GestureDetector added by Scaffold
+    // There is a third GestureDetector added by Scaffold.
     final Finder innerGestureDetectorFinder = find.byType(GestureDetector).at(1);
     final GestureDetector innerGestureDetector = tester.firstWidget<GestureDetector>(innerGestureDetectorFinder);
     expect(innerGestureDetector.behavior, behavior);

examples/layers/raw/canvas.dart

@@ -32,24 +32,24 @@ ui.Picture paint(ui.Rect paintBounds) {
   final double devicePixelRatio = ui.window.devicePixelRatio;
   final ui.Size logicalSize = ui.window.physicalSize / devicePixelRatio;
 
-  // Saves a copy of current transform onto the save stack
+  // Saves a copy of current transform onto the save stack.
   canvas.save();
 
-  // Note that transforms that occur after this point apply only to the
+  // Transforms that occur after this point apply only to the
-  // yellow-bluish rectangle
+  // yellow-bluish rectangle.
 
   // This line will cause the transform to shift entirely outside the paint
   // boundaries, which will cause the canvas interface to discard its
   // commands. Comment it out to see it on screen.
   canvas.translate(-mid.dx / 2.0, logicalSize.height * 2.0);
 
-  // Clips the current transform
+  // Clips the current transform.
   canvas.clipRect(
     ui.Rect.fromLTRB(0, radius + 50, logicalSize.width, logicalSize.height),
     clipOp: ui.ClipOp.difference,
   );
 
-  // Shifts the coordinate space of and rotates the current transform
+  // Shifts the coordinate space of and rotates the current transform.
   canvas.translate(mid.dx, mid.dy);
   canvas.rotate(math.pi/4);
 
@@ -59,14 +59,14 @@ ui.Picture paint(ui.Rect paintBounds) {
     <ui.Color>[const ui.Color(0xFFFFFF00), const ui.Color(0xFF0000FF)],
   );
 
-  // Draws a yellow-bluish rectangle
+  // Draws a yellow-bluish rectangle.
   canvas.drawRect(
     ui.Rect.fromLTRB(-radius, -radius, radius, radius),
     ui.Paint()..shader = yellowBlue,
   );
 
-  // Note that transforms that occur after this point apply only to the
+  // Transforms that occur after this point apply only to the
-  // yellow circle
+  // yellow circle.
 
   // Scale x and y by 0.5.
   final Float64List scaleMatrix = Float64List.fromList(<double>[
@@ -77,20 +77,20 @@ ui.Picture paint(ui.Rect paintBounds) {
   ]);
   canvas.transform(scaleMatrix);
 
-  // Sets paint to transparent yellow
+  // Sets paint to transparent yellow.
   paint.color = const ui.Color.fromARGB(128, 0, 255, 0);
 
-  // Draws a transparent yellow circle
+  // Draws a transparent yellow circle.
   canvas.drawCircle(ui.Offset.zero, radius, paint);
 
-  // Restores the transform from before `save` was called
+  // Restores the transform from before `save` was called.
   canvas.restore();
 
-  // Sets paint to transparent red
+  // Sets paint to transparent red.
   paint.color = const ui.Color.fromARGB(128, 255, 0, 0);
 
-  // Note that this circle is drawn on top of the previous layer that contains
+  // This circle is drawn on top of the previous layer that contains
-  // the rectangle and smaller circle
+  // the rectangle and smaller circle.
   canvas.drawCircle(const ui.Offset(150.0, 300.0), radius, paint);
 
   // When we're done issuing painting commands, we end the recording an receive

packages/flutter/lib/fix_data/README.md

@@ -31,10 +31,10 @@ https://github.com/flutter/flutter/wiki/Data-driven-Fixes
 
 ## When making structural changes to this directory
 
-Note that the tests in this directory are also invoked from external
+The tests in this directory are also invoked from external
-repositories. Specifically, the CI system for the dart-lang/sdk repo runs these
+repositories. Specifically, the CI system for the dart-lang/sdk repo
-tests in order to ensure that changes to the dart fix file format do not break
+runs these tests in order to ensure that changes to the dart fix file
-Flutter.
+format do not break Flutter.
 
 See [tools/bots/flutter/analyze_flutter_flutter.sh](https://github.com/dart-lang/sdk/blob/main/tools/bots/flutter/analyze_flutter_flutter.sh)
 for where the tests are invoked.

packages/flutter/lib/src/cupertino/refresh.dart

@@ -398,7 +398,7 @@ class CupertinoSliverRefreshControl extends StatefulWidget {
     switch (refreshState) {
       case RefreshIndicatorMode.drag:
         // While we're dragging, we draw individual ticks of the spinner while simultaneously
-        // easing the opacity in. Note that the opacity curve values here were derived using
+        // easing the opacity in. The opacity curve values here were derived using
         // Xcode through inspecting a native app running on iOS 13.5.
         const Curve opacityCurve = Interval(0.0, 0.35, curve: Curves.easeInOut);
         return Opacity(

packages/flutter/lib/src/gestures/resampler.dart

@@ -240,7 +240,8 @@ class PointerEventResampler {
       // generated when the position has changed.
       if (event is! PointerMoveEvent && event is! PointerHoverEvent) {
         // Add synthetics `move` or `hover` event if position has changed.
-        // Note: Devices without `hover` events are expected to always have
+        //
+        // Devices without `hover` events are expected to always have
         // `add` and `down` events with the same position and this logic will
         // therefore never produce `hover` events.
         if (position != _position) {

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

@@ -146,15 +146,14 @@ class ButtonBar extends StatelessWidget {
 
   /// The spacing between buttons when the button bar overflows.
   ///
-  /// If the [children] do not fit into a single row, they are
+  /// If the [children] do not fit into a single row, they are arranged into a
-  /// arranged into a column. This parameter provides additional
+  /// column. This parameter provides additional vertical space in between
-  /// vertical space in between buttons when it does overflow.
+  /// buttons when it does overflow.
   ///
-  /// Note that the button spacing may appear to be more than
+  /// The button spacing may appear to be more than the value provided. This is
-  /// the value provided. This is because most buttons adhere to the
+  /// because most buttons adhere to the [MaterialTapTargetSize] of 48px. So,
-  /// [MaterialTapTargetSize] of 48px. So, even though a button
+  /// even though a button might visually be 36px in height, it might still take
-  /// might visually be 36px in height, it might still take up to
+  /// up to 48px vertically.
-  /// 48px vertically.
   ///
   /// If null then no spacing will be added in between buttons in
   /// an overflow state.

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

@@ -482,9 +482,10 @@ class AlertDialog extends StatelessWidget {
   /// Typically used to provide padding to the button bar between the button bar
   /// and the edges of the dialog.
   ///
-  /// If there are no [actions], then no padding will be included. It is also
+  /// The [buttonPadding] may contribute to the padding on the edges of
-  /// important to note that [buttonPadding] may contribute to the padding on
+  /// [actions] as well.
-  /// the edges of [actions] as well.
+  ///
+  /// If there are no [actions], then no padding will be included.
   ///
   /// {@tool snippet}
   /// This is an example of a set of actions aligned with the content widget.
@@ -546,21 +547,20 @@ class AlertDialog extends StatelessWidget {
   /// * [OverflowBar], which [actions] configures to lay itself out.
   final VerticalDirection? actionsOverflowDirection;
 
-  /// The spacing between [actions] when the [OverflowBar] switches
+  /// The spacing between [actions] when the [OverflowBar] switches to a column
-  /// to a column layout because the actions don't fit horizontally.
+  /// layout because the actions don't fit horizontally.
   ///
   /// If the widgets in [actions] do not fit into a single row, they are
-  /// arranged into a column. This parameter provides additional
+  /// arranged into a column. This parameter provides additional vertical space
-  /// vertical space in between buttons when it does overflow.
+  /// between buttons when it does overflow.
   ///
-  /// Note that the button spacing may appear to be more than
+  /// The button spacing may appear to be more than the value provided. This is
-  /// the value provided. This is because most buttons adhere to the
+  /// because most buttons adhere to the [MaterialTapTargetSize] of 48px. So,
-  /// [MaterialTapTargetSize] of 48px. So, even though a button
+  /// even though a button might visually be 36px in height, it might still take
-  /// might visually be 36px in height, it might still take up to
+  /// up to 48px vertically.
-  /// 48px vertically.
   ///
-  /// If null then no spacing will be added in between buttons in
+  /// If null then no spacing will be added in between buttons in an overflow
-  /// an overflow state.
+  /// state.
   final double? actionsOverflowButtonSpacing;
 
   /// The padding that surrounds each button in [actions].

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

@@ -118,7 +118,6 @@ class ExpansionPanel {
 ///
 /// See [ExpansionPanelList.radio] for a sample implementation.
 class ExpansionPanelRadio extends ExpansionPanel {
-
   /// An expansion panel that allows for radio functionality.
   ///
   /// A unique [value] must be passed into the constructor. The
@@ -139,19 +138,24 @@ class ExpansionPanelRadio extends ExpansionPanel {
 /// A material expansion panel list that lays out its children and animates
 /// expansions.
 ///
-/// Note that [expansionCallback] behaves differently for [ExpansionPanelList]
+/// The [expansionCallback] is called when the expansion state changes. For
-/// and [ExpansionPanelList.radio].
+/// normal [ExpansionPanelList] widgets, it is the responsibilty of the parent
+/// widget to rebuild the [ExpansionPanelList] with updated values for
+/// [ExpansionPanel.isExpanded]. For [ExpansionPanelList.radio] widgets, the
+/// open state is tracked internally and the callback is invoked both for the
+/// previously open panel, which is closing, and the previously closed panel,
+/// which is opening.
 ///
 /// {@tool dartpad}
-/// Here is a simple example of how to implement ExpansionPanelList.
+/// Here is a simple example of how to use [ExpansionPanelList].
 ///
 /// ** See code in examples/api/lib/material/expansion_panel/expansion_panel_list.0.dart **
 /// {@end-tool}
 ///
 /// See also:
 ///
-///  * [ExpansionPanel]
+///  * [ExpansionPanel], which is used in the [children] property.
-///  * [ExpansionPanelList.radio]
+///  * [ExpansionPanelList.radio], a variant of this widget where only one panel is open at a time.
 ///  * <https://material.io/design/components/lists.html#types>
 class ExpansionPanelList extends StatefulWidget {
   /// Creates an expansion panel list widget. The [expansionCallback] is
@@ -208,10 +212,11 @@ class ExpansionPanelList extends StatefulWidget {
   /// 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 should call [State.setState] when
-  /// about the closing/opening panel. On the other hand, the callback for
+  /// it is notified about the closing/opening panel. On the other hand, the
-  /// [ExpansionPanelList.radio] is intended to inform the parent widget of
+  /// callback for [ExpansionPanelList.radio] is intended to inform the parent
-  /// changes, as the radio panels' open/close states are managed internally.
+  /// 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
   /// panels in a parent widget that may need to react to these changes.

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

@@ -83,7 +83,7 @@ class ExpansionTile extends StatefulWidget {
   ///
   /// Typically a [CircleAvatar] widget.
   ///
-  /// Note that depending on the value of [controlAffinity], the [leading] widget
+  /// Depending on the value of [controlAffinity], the [leading] widget
   /// may replace the rotating expansion arrow icon.
   final Widget? leading;
 
@@ -133,7 +133,7 @@ class ExpansionTile extends StatefulWidget {
 
   /// A widget to display after the title.
   ///
-  /// Note that depending on the value of [controlAffinity], the [trailing] widget
+  /// Depending on the value of [controlAffinity], the [trailing] widget
   /// may replace the rotating expansion arrow icon.
   final Widget? trailing;
 
@@ -187,17 +187,19 @@ class ExpansionTile extends StatefulWidget {
   /// Specifies the alignment of each child within [children] when the tile is expanded.
   ///
   /// The internals of the expanded tile make use of a [Column] widget for
-  /// [children], and the `crossAxisAlignment` parameter is passed directly into the [Column].
+  /// [children], and the `crossAxisAlignment` parameter is passed directly into
+  /// the [Column].
   ///
   /// Modifying this property controls the cross axis alignment of each child
-  /// within its [Column]. Note that the width of the [Column] that houses
+  /// within its [Column]. The width of the [Column] that houses [children] will
-  /// [children] will be the same as the widest child widget in [children]. It is
+  /// be the same as the widest child widget in [children]. The width of the
-  /// not necessarily the width of [Column] is equal to the width of expanded tile.
+  /// [Column] might not be equal to the width of the expanded tile.
   ///
-  /// To align the [Column] along the expanded tile, use the [expandedAlignment] property
+  /// To align the [Column] along the expanded tile, use the [expandedAlignment]
-  /// instead.
+  /// property instead.
   ///
-  /// When the value is null, the value of [expandedCrossAxisAlignment] is [CrossAxisAlignment.center].
+  /// When the value is null, the value of [expandedCrossAxisAlignment] is
+  /// [CrossAxisAlignment.center].
   final CrossAxisAlignment? expandedCrossAxisAlignment;
 
   /// Specifies padding for [children].

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

@@ -2741,7 +2741,7 @@ class InputDecoration {
   /// If null, defaults to a value derived from the base [TextStyle] for the
   /// input field and the current [Theme].
   ///
-  /// Note that if you specify this style it will override the default behavior
+  /// Specifying this style will override the default behavior
   /// of [InputDecoration] that changes the color of the label to the
   /// [InputDecoration.errorStyle] color or [ColorScheme.error].
   ///
@@ -2771,7 +2771,7 @@ class InputDecoration {
   ///
   /// If null, defaults to [labelStyle].
   ///
-  /// Note that if you specify this style it will override the default behavior
+  /// Specifying this style will override the default behavior
   /// of [InputDecoration] that changes the color of the label to the
   /// [InputDecoration.errorStyle] color or [ColorScheme.error].
   ///
@@ -2871,8 +2871,8 @@ class InputDecoration {
   /// By default the color of style will be used by the label of
   /// [InputDecoration] if [InputDecoration.errorText] is not null. See
   /// [InputDecoration.labelStyle] or [InputDecoration.floatingLabelStyle] for
-  /// an example of how to replicate this behavior if you have specified either
+  /// an example of how to replicate this behavior when specifying those
-  /// style.
+  /// styles.
   /// {@endtemplate}
   final TextStyle? errorStyle;
 
@@ -3022,7 +3022,7 @@ class InputDecoration {
   /// This example shows the differences between two `TextField` widgets when
   /// [prefixIconConstraints] is set to the default value and when one is not.
   ///
-  /// Note that [isDense] must be set to true to be able to
+  /// The [isDense] property must be set to true to be able to
   /// set the constraints smaller than 48px.
   ///
   /// If null, [BoxConstraints] with a minimum width and height of 48px is
@@ -3199,7 +3199,7 @@ class InputDecoration {
   /// This example shows the differences between two `TextField` widgets when
   /// [suffixIconConstraints] is set to the default value and when one is not.
   ///
-  /// Note that [isDense] must be set to true to be able to
+  /// The [isDense] property must be set to true to be able to
   /// set the constraints smaller than 48px.
   ///
   /// If null, [BoxConstraints] with a minimum width and height of 48px is

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

@@ -131,7 +131,7 @@ enum ListTileTitleAlignment {
 /// see the example below to see how to adhere to both Material spec and
 /// accessibility requirements.
 ///
-/// Note that [leading] and [trailing] widgets can expand as far as they wish
+/// The [leading] and [trailing] widgets can expand as far as they wish
 /// horizontally, so ensure that they are properly constrained.
 ///
 /// List tiles are typically used in [ListView]s, or arranged in [Column]s in

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

@@ -251,7 +251,7 @@ class PopupMenuItem<T> extends PopupMenuEntry<T> {
 
   /// The padding of the menu item.
   ///
-  /// Note that [height] may interact with the applied padding. For example,
+  /// The [height] property may interact with the applied padding. For example,
   /// If a [height] greater than the height of the sum of the padding and [child]
   /// is provided, then the padding's effect will not be visible.
   ///

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

@@ -802,8 +802,8 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// [MaterialState.selected] state, i.e. if the [Tab] is selected or not,
   /// ignoring [unselectedLabelColor] even if it's non-null.
   ///
-  /// Note: [labelStyle]'s color and [TabBarTheme.labelStyle]'s color do not
+  /// The color specified in the [labelStyle] and the [TabBarTheme.labelStyle]
-  /// affect the effective [labelColor].
+  /// do not affect the effective [labelColor].
   ///
   /// See also:
   ///
@@ -822,9 +822,9 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// will be used, otherwise unselected tab labels are rendered with
   /// [labelColor] at 70% opacity.
   ///
-  /// Note: [unselectedLabelStyle]'s color and
+  /// The color specified in the [unselectedLabelStyle] and the
-  /// [TabBarTheme.unselectedLabelStyle]'s color are ignored in
+  /// [TabBarTheme.unselectedLabelStyle] are ignored in [unselectedLabelColor]'s
-  /// [unselectedLabelColor]'s precedence calculation.
+  /// precedence calculation.
   ///
   /// See also:
   ///

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

@@ -82,9 +82,9 @@ class TextTheme with Diagnosticable {
   /// If you do decide to create your own text theme, consider using one of
   /// those predefined themes as a starting point for [copyWith] or [apply].
   ///
-  /// Please note that you can not mix and match the 2018 styles with the 2021
+  /// The 2018 styles cannot be mixed with the 2021 styles. Only one or the
-  /// styles. Only one or the other is allowed in this constructor. The 2018
+  /// other is allowed in this constructor. The 2018 styles are deprecated and
-  /// styles will be deprecated and removed eventually.
+  /// will eventually be removed.
   const TextTheme({
     TextStyle? displayLarge,
     TextStyle? displayMedium,

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

@@ -1138,10 +1138,11 @@ class ThemeData with Diagnosticable {
   /// will aim to only support Material 3.
   ///
   /// ## Defaults
-  /// If a [ThemeData] is constructed with [useMaterial3] set to true, then
+  ///
-  /// some properties will get updated defaults. Please note that
+  /// If a [ThemeData] is _constructed_ with [useMaterial3] set to true, then
-  /// [ThemeData.copyWith] with [useMaterial3] set to true will
+  /// some properties will get updated defaults. However, the
-  /// not change any of these properties in the resulting [ThemeData].
+  /// [ThemeData.copyWith] method with [useMaterial3] set to true will _not_
+  /// change any of these properties in the resulting [ThemeData].
   ///
   /// <style>table,td,th { border-collapse: collapse; padding: 0.45em; } td { border: 1px solid }</style>
   ///

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

@@ -26,8 +26,8 @@ enum BorderStyle {
 /// A [Border] consists of four [BorderSide] objects: [Border.top],
 /// [Border.left], [Border.right], and [Border.bottom].
 ///
-/// Note that setting [BorderSide.width] to 0.0 will result in hairline
+/// Setting [BorderSide.width] to 0.0 will result in hairline rendering; see
-/// rendering. A more involved explanation is present in [BorderSide.width].
+/// [BorderSide.width] for a more involved explanation.
 ///
 /// {@tool snippet}
 /// This sample shows how [BorderSide] objects can be used in a [Container], via
@@ -108,7 +108,7 @@ class BorderSide with Diagnosticable {
   /// The width of this side of the border, in logical pixels.
   ///
   /// Setting width to 0.0 will result in a hairline border. This means that
-  /// the border will have the width of one physical pixel. Also, hairline
+  /// the border will have the width of one physical pixel. Hairline
   /// rendering takes shortcuts when the path overlaps a pixel more than once.
   /// This means that it will render faster than otherwise, but it might
   /// double-hit pixels, giving it a slightly darker/lighter result.
@@ -143,6 +143,11 @@ class BorderSide with Diagnosticable {
   /// - [strokeAlignCenter] provides padding with half [width].
   /// - [strokeAlignOutside] provides zero padding, as stroke is drawn entirely outside.
   ///
+  /// This property is not honored by [toPaint] (because the [Paint] object
+  /// cannot represent it); it is intended that classes that use [BorderSide]
+  /// objects implement this property when painting borders by suitably
+  /// inflating or deflating their regions.
+  ///
   /// {@tool dartpad}
   /// This example shows an animation of how [strokeAlign] affects the drawing
   /// when applied to borders of various shapes.
@@ -153,15 +158,21 @@ class BorderSide with Diagnosticable {
 
   /// The border is drawn fully inside of the border path.
   ///
-  /// This is the default.
+  /// This is a constant for use with [strokeAlign].
+  ///
+  /// This is the default value for [strokeAlign].
   static const double strokeAlignInside = -1.0;
 
   /// The border is drawn on the center of the border path, with half of the
   /// [BorderSide.width] on the inside, and the other half on the outside of
   /// the path.
+  ///
+  /// This is a constant for use with [strokeAlign].
   static const double strokeAlignCenter = 0.0;
 
   /// The border is drawn on the outside of the border path.
+  ///
+  /// This is a constant for use with [strokeAlign].
   static const double strokeAlignOutside = 1.0;
 
   /// Creates a copy of this border but with the given fields replaced with the new values.
@@ -206,6 +217,9 @@ class BorderSide with Diagnosticable {
   /// Create a [Paint] object that, if used to stroke a line, will draw the line
   /// in this border's style.
   ///
+  /// The [strokeAlign] property is not reflected in the [Paint]; consumers must
+  /// implement that directly by inflating or deflating their region appropriately.
+  ///
   /// Not all borders use this method to paint their border sides. For example,
   /// non-uniform rectangular [Border]s have beveled edges and so paint their
   /// border sides as filled shapes rather than using a stroke.

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

@@ -69,7 +69,7 @@ abstract class Decoration with Diagnosticable {
   ///
   /// When implementing this method in subclasses, return null if this class
   /// cannot interpolate from `a`. In that case, [lerp] will try `a`'s [lerpTo]
-  /// method instead.
+  /// method instead. Classes should implement both [lerpFrom] and [lerpTo].
   ///
   /// Supporting interpolating from null is recommended as the [Decoration.lerp]
   /// method uses this as a fallback when two classes can't interpolate between
@@ -95,11 +95,11 @@ abstract class Decoration with Diagnosticable {
   /// Linearly interpolates from `this` to another [Decoration] (which may be of
   /// a different class).
   ///
-  /// This is called if `b`'s [lerpTo] did not know how to handle this class.
+  /// This is called if `b`'s [lerpFrom] did not know how to handle this class.
   ///
   /// When implementing this method in subclasses, return null if this class
   /// cannot interpolate from `b`. In that case, [lerp] will apply a default
-  /// behavior instead.
+  /// behavior instead. Classes should implement both [lerpFrom] and [lerpTo].
   ///
   /// Supporting interpolating to null is recommended as the [Decoration.lerp]
   /// method uses this as a fallback when two classes can't interpolate between

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

@@ -32,7 +32,7 @@ abstract class AssetManifest {
 
   /// Retrieves metadata about an asset and its variants.
   ///
-  /// Note that this method considers a main asset to be a variant of itself and
+  /// This method considers a main asset to be a variant of itself and
   /// includes it in the returned list.
   ///
   /// Throws an [ArgumentError] if [key] cannot be found within the manifest. To

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

@@ -432,10 +432,10 @@ abstract class RawKeyEvent with Diagnosticable {
   /// Returns true if a ALT modifier key is pressed, regardless of which side
   /// of the keyboard it is on.
   ///
-  /// Note that the ALTGR key that appears on some keyboards is considered to be
+  /// The `AltGr` key that appears on some keyboards is considered to be
   /// the same as [LogicalKeyboardKey.altRight] on some platforms (notably
   /// Android). On platforms that can distinguish between `altRight` and
-  /// `altGr`, a press of `altGr` will not return true here, and will need to be
+  /// `altGr`, a press of `AltGr` will not return true here, and will need to be
   /// tested for separately.
   ///
   /// Use [isKeyPressed] if you need to know which alt key was pressed.

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

@@ -648,7 +648,7 @@ class DragTarget<T extends Object> extends StatefulWidget {
 
   /// Called when a [Draggable] moves within this [DragTarget].
   ///
-  /// Note that this includes entering and leaving the target.
+  /// This includes entering and leaving the target.
   final DragTargetMove<T>? onMove;
 
   /// How to behave during hit testing.

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

@@ -531,8 +531,8 @@ class _DraggableSheetExtent {
   /// Start an activity that affects the sheet and register a cancel call back
   /// that will be called if another activity starts.
   ///
-  /// Note that `onCanceled` will get called even if the subsequent activity
+  /// The `onCanceled` callback will get called even if the subsequent activity
-  /// started after this one finished so `onCanceled` should be safe to call at
+  /// started after this one finished, so `onCanceled` must be safe to call at
   /// any time.
   void startActivity({required VoidCallback onCanceled}) {
     _cancelActivity?.call();

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

@@ -1082,7 +1082,7 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
     _doRequestFocus(findFirstFocus: true);
   }
 
-  // Note that this is overridden in FocusScopeNode.
+  // This is overridden in FocusScopeNode.
   void _doRequestFocus({required bool findFirstFocus}) {
     if (!canRequestFocus) {
       assert(_focusDebug(() => 'Node NOT requesting focus because canRequestFocus is false: $this'));

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

@@ -941,7 +941,7 @@ class GestureDetector extends StatelessWidget {
   /// force to initiate a force press. The amount of force is at least
   /// [ForcePressGestureRecognizer.startPressure].
   ///
-  /// Note that this callback will only be fired on devices with pressure
+  /// This callback will only be fired on devices with pressure
   /// detecting screens.
   final GestureForcePressStartCallback? onForcePressStart;
 
@@ -949,7 +949,7 @@ class GestureDetector extends StatelessWidget {
   /// force. The amount of force is at least
   /// [ForcePressGestureRecognizer.peakPressure].
   ///
-  /// Note that this callback will only be fired on devices with pressure
+  /// This callback will only be fired on devices with pressure
   /// detecting screens.
   final GestureForcePressPeakCallback? onForcePressPeak;
 
@@ -958,13 +958,13 @@ class GestureDetector extends StatelessWidget {
   /// plane of the screen, pressing the screen with varying forces or both
   /// simultaneously.
   ///
-  /// Note that this callback will only be fired on devices with pressure
+  /// This callback will only be fired on devices with pressure
   /// detecting screens.
   final GestureForcePressUpdateCallback? onForcePressUpdate;
 
-  /// The pointer is no longer in contact with the screen.
+  /// The pointer tracked by [onForcePressStart] is no longer in contact with the screen.
   ///
-  /// Note that this callback will only be fired on devices with pressure
+  /// This callback will only be fired on devices with pressure
   /// detecting screens.
   final GestureForcePressEndCallback? onForcePressEnd;
 

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

@@ -3711,8 +3711,8 @@ class _WidgetFactory {
 /// factory. The framework will then instrument that function in the same way
 /// as it does for [Widget] constructors.
 ///
-/// Note that the function **must not** have optional positional parameters for
+/// Tracking will not work correctly if the function has optional positional
-/// tracking to work correctly.
+/// parameters.
 ///
 /// Currently this annotation is only supported on extension methods.
 ///

packages/flutter/test/material/floating_action_button_location_test.dart

@@ -125,7 +125,7 @@ void main() {
           // Measure the delta in rotation.
           // Check that it never grows by more than a safe amount.
           //
-          // Note that there may be multiple transitions all active at
+          // There may be multiple transitions all active at
           // the same time. We are concerned only with the closest one.
           final Iterable<RotationTransition> rotationTransitions = tester.widgetList(
             find.byType(RotationTransition),

packages/flutter/test/material/paginated_data_table_test.dart

@@ -771,7 +771,7 @@ void main() {
   testWidgets('PaginatedDataTable table fills Card width', (WidgetTester tester) async {
     final TestDataSource source = TestDataSource();
 
-    // Note: 800 is wide enough to ensure that all of the columns fit in the
+    // 800 is wide enough to ensure that all of the columns fit in the
     // Card. The test makes sure that the DataTable is exactly as wide
     // as the Card, minus the Card's margin.
     const double originalWidth = 800;

packages/flutter/test/material/scaffold_test.dart

@@ -1190,7 +1190,7 @@ void main() {
     expect(tester.getRect(find.byKey(appBar)), const Rect.fromLTRB(0.0, 0.0, 800.0, 43.0));
     expect(tester.getRect(find.byKey(body)), const Rect.fromLTRB(0.0, 43.0, 800.0, 400.0));
     expect(tester.getRect(find.byKey(floatingActionButton)), rectMoreOrLessEquals(const Rect.fromLTRB(36.0, 307.0, 113.0, 384.0)));
-    expect(tester.getRect(find.byKey(persistentFooterButton)),const  Rect.fromLTRB(28.0, 417.0, 128.0, 507.0)); // Note: has 8px each top/bottom padding.
+    expect(tester.getRect(find.byKey(persistentFooterButton)),const  Rect.fromLTRB(28.0, 417.0, 128.0, 507.0)); // Includes 8px each top/bottom padding.
     expect(tester.getRect(find.byKey(drawer)), const Rect.fromLTRB(596.0, 0.0, 800.0, 600.0));
     expect(tester.getRect(find.byKey(bottomNavigationBar)), const Rect.fromLTRB(0.0, 515.0, 800.0, 600.0));
     expect(tester.getRect(find.byKey(insideAppBar)), const Rect.fromLTRB(20.0, 30.0, 750.0, 43.0));
@@ -1285,7 +1285,7 @@ void main() {
     expect(tester.getRect(find.byKey(appBar)), const Rect.fromLTRB(0.0, 0.0, 800.0, 43.0));
     expect(tester.getRect(find.byKey(body)), const Rect.fromLTRB(0.0, 43.0, 800.0, 400.0));
     expect(tester.getRect(find.byKey(floatingActionButton)), rectMoreOrLessEquals(const Rect.fromLTRB(36.0, 307.0, 113.0, 384.0)));
-    expect(tester.getRect(find.byKey(persistentFooterButton)), const Rect.fromLTRB(28.0, 442.0, 128.0, 532.0)); // Note: has 8px each top/bottom padding.
+    expect(tester.getRect(find.byKey(persistentFooterButton)), const Rect.fromLTRB(28.0, 442.0, 128.0, 532.0)); // Includes 8px each top/bottom padding.
     expect(tester.getRect(find.byKey(drawer)), const Rect.fromLTRB(596.0, 0.0, 800.0, 600.0));
     expect(tester.getRect(find.byKey(insideAppBar)), const Rect.fromLTRB(20.0, 30.0, 750.0, 43.0));
     expect(tester.getRect(find.byKey(insideBody)), const Rect.fromLTRB(20.0, 43.0, 750.0, 400.0));

packages/flutter/test/widgets/semantics_test.dart

@@ -551,7 +551,7 @@ void main() {
 
   testWidgets('Semantics widget supports all flags', (WidgetTester tester) async {
     final SemanticsTester semantics = SemanticsTester(tester);
-    // Note: checked state and toggled state are mutually exclusive.
+    // Checked state and toggled state are mutually exclusive.
     await tester.pumpWidget(
         Semantics(
           key: const Key('a'),

packages/flutter/test_fixes/README.md

@@ -21,10 +21,10 @@ https://github.com/flutter/flutter/wiki/Data-driven-Fixes
 
 ## When making structural changes to this directory
 
-Note that the tests in this directory are also invoked from external
+The tests in this directory are also invoked from external
-repositories. Specifically, the CI system for the dart-lang/sdk repo runs these
+repositories. Specifically, the CI system for the dart-lang/sdk repo
-tests in order to ensure that changes to the dart fix file format do not break
+runs these tests in order to ensure that changes to the dart fix file
-Flutter.
+format do not break Flutter.
 
 See [tools/bots/flutter/analyze_flutter_flutter.sh](https://github.com/dart-lang/sdk/blob/main/tools/bots/flutter/analyze_flutter_flutter.sh)
 for where the tests are invoked.

packages/flutter/test_fixes/material/app_bar_theme.dart

@@ -15,7 +15,7 @@ void main() {
   appBarTheme = appBarTheme.copyWith(brightness: Brightness.dark);
   appBarTheme.brightness;
 
-  TextTheme myTextTheme = TextTheme(); 
+  TextTheme myTextTheme = TextTheme();
   AppBarTheme appBarTheme = AppBarTheme();
   appBarTheme = AppBarTheme(textTheme: myTextTheme);
   appBarTheme = AppBarTheme(textTheme: myTextTheme);

packages/flutter_driver/lib/src/driver/profiling_summarizer.dart

@@ -70,7 +70,7 @@ class ProfilingSummarizer {
   final Map<ProfileType, List<TimelineEvent>> eventByType;
 
   /// Returns the average, 90th and 99th percentile summary of CPU, GPU and Memory
-  /// usage from the recorded events. Note: If a given profile type isn't available
+  /// usage from the recorded events. If a given profile type isn't available
   /// for any reason, the map will not contain the said profile type.
   Map<String, dynamic> summarize() {
     final Map<String, dynamic> summary = <String, dynamic>{};

packages/flutter_driver/lib/src/extension/extension.dart

@@ -97,7 +97,7 @@ class _DriverBinding extends BindingBase with SchedulerBinding, ServicesBinding,
 /// driver.sendCommand(SomeCommand(ByValueKey('Button'), 7));
 /// ```
 ///
-/// Note: SomeFinder and SomeFinderExtension must be placed in different files
+/// `SomeFinder` and `SomeFinderExtension` must be placed in different files
 /// to avoid `dart:ui` import issue. Imports relative to `dart:ui` can't be
 /// accessed from host runner, where flutter runtime is not accessible.
 ///
@@ -140,7 +140,7 @@ class _DriverBinding extends BindingBase with SchedulerBinding, ServicesBinding,
 /// }
 /// ```
 ///
-/// Note: SomeCommand, SomeResult and SomeCommandExtension must be placed in
+/// `SomeCommand`, `SomeResult` and `SomeCommandExtension` must be placed in
 /// different files to avoid `dart:ui` import issue. Imports relative to `dart:ui`
 /// can't be accessed from host runner, where flutter runtime is not accessible.
 ///

packages/flutter_test/lib/src/widget_tester.dart

@@ -499,12 +499,34 @@ Future<void> expectLater(
 
 /// Class that programmatically interacts with widgets and the test environment.
 ///
+/// Typically, a test uses [pumpWidget] to load a widget tree (in a manner very
+/// similar to how [runApp] works in a Flutter application). Then, methods such
+/// as [tap], [drag], [enterText], [fling], [longPress], etc, can be used to
+/// interact with the application. The application runs in a [FakeAsync] zone,
+/// which allows time to be stepped forward deliberately; this is done using the
+/// [pump] method.
+///
+/// The [expect] function can then be used to examine the state of the
+/// application, typically using [Finder]s such as those in the [find]
+/// namespace, and [Matcher]s such as [findsOneWidget].
+///
+/// ```dart
+/// testWidgets('MyWidget', (WidgetTester tester) async {
+///   await tester.pumpWidget(MyWidget());
+///   await tester.tap(find.text('Save'));
+///   await tester.pump(); // allow the application to handle
+///   await tester.pump(const Duration(seconds: 1)); // skip past the animation
+///   expect(find.text('Success'), findsOneWidget);
+/// });
+/// ```
+///
 /// For convenience, instances of this class (such as the one provided by
 /// `testWidgets`) can be used as the `vsync` for `AnimationController` objects.
 ///
 /// When the binding is [LiveTestWidgetsFlutterBinding], events from
 /// [LiveTestWidgetsFlutterBinding.deviceEventDispatcher] will be handled in
-/// [dispatchEvent].
+/// [dispatchEvent]. Thus, using `flutter run` to run a test lets one tap on
+/// the screen to generate [Finder]s relevant to the test.
 class WidgetTester extends WidgetController implements HitTestDispatcher, TickerProvider {
   WidgetTester._(super.binding) {
     if (binding is LiveTestWidgetsFlutterBinding) {

packages/flutter_tools/bin/podhelper.rb

@@ -180,8 +180,8 @@ def flutter_install_ios_engine_pod(ios_application_path = nil)
   File.open(copied_podspec_path, 'w') do |podspec|
     podspec.write <<~EOF
       #
-      # NOTE: This podspec is NOT to be published. It is only used as a local source!
+      # This podspec is NOT to be published. It is only used as a local source!
-      #       This is a generated file; do not edit or check into version control.
+      # This is a generated file; do not edit or check into version control.
       #
 
       Pod::Spec.new do |s|
@@ -218,8 +218,8 @@ def flutter_install_macos_engine_pod(mac_application_path = nil)
   File.open(copied_podspec_path, 'w') do |podspec|
     podspec.write <<~EOF
       #
-      # NOTE: This podspec is NOT to be published. It is only used as a local source!
+      # This podspec is NOT to be published. It is only used as a local source!
-      #       This is a generated file; do not edit or check into version control.
+      # This is a generated file; do not edit or check into version control.
       #
 
       Pod::Spec.new do |s|

packages/flutter_tools/gradle/app_plugin_loader.gradle

@@ -9,7 +9,7 @@ import groovy.json.JsonSlurper
 
 def flutterProjectRoot = rootProject.projectDir.parentFile
 
-// Note: if this logic is changed, also change the logic in module_plugin_loader.gradle.
+// If this logic is changed, also change the logic in module_plugin_loader.gradle.
 def pluginsFile = new File(flutterProjectRoot, '.flutter-plugins-dependencies')
 if (!pluginsFile.exists()) {
   return

packages/flutter_tools/gradle/flutter.gradle

@@ -279,9 +279,8 @@ class FlutterPlugin implements Plugin<Project> {
                     // Enables code shrinking, obfuscation, and optimization for only
                     // your project's release build type.
                     minifyEnabled true
-                    // Enables resource shrinking, which is performed by the
+                    // Enables resource shrinking, which is performed by the Android Gradle plugin.
-                    // Android Gradle plugin.
+                    // The resource shrinker can't be used for libraries.
-                    // NOTE: The resource shrinker can't be used for libraries.
                     shrinkResources isBuiltAsApp(project)
                     // Fallback to `android/app/proguard-rules.pro`.
                     // This way, custom Proguard rules can be configured as needed.
@@ -682,7 +681,7 @@ class FlutterPlugin implements Plugin<Project> {
     /**
      * Returns a Flutter build mode suitable for the specified Android buildType.
      *
-     * Note: The BuildType DSL type is not public, and is therefore omitted from the signature.
+     * The BuildType DSL type is not public, and is therefore omitted from the signature.
      *
      * @return "debug", "profile", or "release" (fall-back).
      */

packages/flutter_tools/gradle/module_plugin_loader.gradle

@@ -11,7 +11,7 @@ def moduleProjectRoot = project(':flutter').projectDir.parentFile.parentFile
 
 def object = null;
 String flutterModulePath = project(':flutter').projectDir.parentFile.getAbsolutePath()
-// Note: if this logic is changed, also change the logic in app_plugin_loader.gradle.
+// If this logic is changed, also change the logic in app_plugin_loader.gradle.
 def pluginsFile = new File(moduleProjectRoot, '.flutter-plugins-dependencies')
 if (pluginsFile.exists()) {
     object = new JsonSlurper().parseText(pluginsFile.text)

packages/flutter_tools/lib/src/android/gradle_errors.dart

@@ -461,8 +461,8 @@ final GradleHandledError minSdkVersionHandler = GradleHandledError(
     globals.printBox(
       'The plugin ${minSdkVersionMatch?.group(3)} requires a higher Android SDK version.\n'
       '$textInBold\n'
-      "Note that your app won't be available to users running Android SDKs below ${minSdkVersionMatch?.group(2)}.\n"
+      'Following this change, your app will not be available to users running Android SDKs below ${minSdkVersionMatch?.group(2)}.\n'
-      'Alternatively, try to find a version of this plugin that supports these lower versions of the Android SDK.\n'
+      'Consider searching for a version of this plugin that supports these lower versions of the Android SDK instead.\n'
       'For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration',
       title: _boxTitle,
     );

packages/flutter_tools/lib/src/base/config.dart

@@ -189,7 +189,7 @@ class Config {
   //
   // If the searched environment variables are not set, '.' is returned instead.
   //
-  // Note that this is different from FileSystemUtils.homeDirPath.
+  // This is different from [FileSystemUtils.homeDirPath].
   static String _userHomePath(Platform platform) {
     final String envKey = platform.isWindows ? 'APPDATA' : 'HOME';
     return platform.environment[envKey] ?? '.';

packages/flutter_tools/lib/src/build_system/build_system.dart

@@ -303,7 +303,7 @@ class CompositeTarget extends Target {
 ///
 /// Example (Good):
 ///
-/// Using the build mode to produce different output. Note that the action
+/// Using the build mode to produce different output. The action
 /// is still responsible for outputting a different file, as defined by the
 /// corresponding output [Source].
 ///

packages/flutter_tools/lib/src/build_system/targets/common.dart

@@ -117,7 +117,7 @@ class ReleaseCopyFlutterBundle extends CopyFlutterBundle {
 
 /// Generate a snapshot of the dart code used in the program.
 ///
-/// Note that this target depends on the `.dart_tool/package_config.json` file
+/// This target depends on the `.dart_tool/package_config.json` file
 /// even though it is not listed as an input. Pub inserts a timestamp into
 /// the file which causes unnecessary rebuilds, so instead a subset of the contents
 /// are used an input instead.

packages/flutter_tools/lib/src/commands/build_aar.dart

@@ -99,9 +99,8 @@ class BuildAarCommand extends BuildSubCommand {
   final String description = 'Build a repository containing an AAR and a POM file.\n\n'
       'By default, AARs are built for `release`, `debug` and `profile`.\n'
       'The POM file is used to include the dependencies that the AAR was compiled against.\n'
-      'To learn more about how to use these artifacts, see '
+      'To learn more about how to use these artifacts, see: https://flutter.dev/go/build-aar\n'
-      'https://flutter.dev/go/build-aar\n'
+      'This command assumes that the entrypoint is "lib/main.dart". '
-      'Note: this command builds applications assuming that the entrypoint is lib/main.dart. '
       'This cannot currently be configured.';
 
   @override

packages/flutter_tools/lib/src/custom_devices/custom_device.dart

@@ -166,11 +166,11 @@ class CustomDevicePortForwarder extends DevicePortForwarder {
 
     final Completer<ForwardedPort?> completer = Completer<ForwardedPort?>();
 
-    // read the outputs of the process, if we find a line that matches
+    // Read the outputs of the process; if we find a line that matches
     // the configs forwardPortSuccessRegex, we complete with a successfully
-    // forwarded port
+    // forwarded port.
-    // Note that if that regex never matches, this will potentially run forever
+    // If that regex never matches, this will potentially run forever
-    // and the forwarding will never complete
+    // and the forwarding will never complete.
     final CustomDeviceLogReader reader = CustomDeviceLogReader(_deviceName)..listenToProcessOutput(process);
     final StreamSubscription<String> logLinesSubscription = reader.logLines.listen((String line) {
       if (_forwardPortSuccessRegex.hasMatch(line) && !completer.isCompleted) {

packages/flutter_tools/lib/src/device.dart

@@ -278,7 +278,7 @@ abstract class DeviceManager {
         // user only typed 'flutter run' and both an Android device and desktop
         // device are available, choose the Android device.
 
-        // Note: ephemeral is nullable for device types where this is not well
+        // Ephemeral is nullable for device types where this is not well
         // defined.
         final List<Device> ephemeralDevices = <Device>[
           for (final Device device in devices)

packages/flutter_tools/lib/src/fuchsia/fuchsia_device.dart

@@ -696,7 +696,7 @@ class FuchsiaDevice extends Device {
   Future<int> findIsolatePort(String isolateName, List<int> ports) async {
     for (final int port in ports) {
       try {
-        // Note: The square-bracket enclosure for using the IPv6 loopback
+        // The square-bracket enclosure for using the IPv6 loopback
         // didn't appear to work, but when assigning to the IPv4 loopback device,
         // netstat shows that the local port is actually being used on the IPv6
         // loopback (::1).
@@ -848,7 +848,7 @@ class _FuchsiaPortForwarder extends DevicePortForwarder {
       throwToolExit('Cannot interact with device. No ssh config.\n'
           'Try setting FUCHSIA_SSH_CONFIG or FUCHSIA_BUILD_DIR.');
     }
-    // Note: the provided command works around a bug in -N, see US-515
+    // The provided command works around a bug in -N, see US-515
     // for more explanation.
     final List<String> command = <String>[
       'ssh',

packages/flutter_tools/lib/src/ios/xcode_build_settings.dart

@@ -181,7 +181,7 @@ Future<List<String>> _xcodeBuildSettingsLines({
     // Tell Xcode not to build universal binaries for local engines, which are
     // single-architecture.
     //
-    // NOTE: this assumes that local engine binary paths are consistent with
+    // This assumes that local engine binary paths are consistent with
     // the conventions uses in the engine: 32-bit iOS engines are built to
     // paths ending in _arm, 64-bit builds are not.
 

packages/flutter_tools/lib/src/isolated/devfs_web.dart

@@ -1034,7 +1034,7 @@ void log(logging.LogRecord event) {
   if (event.level >= logging.Level.SEVERE) {
     globals.printError('${event.loggerName}: ${event.message}$error', stackTrace: event.stackTrace);
   } else if (event.level == logging.Level.WARNING) {
-    // Note: Temporary fix for https://github.com/flutter/flutter/issues/109792
+    // Temporary fix for https://github.com/flutter/flutter/issues/109792
     // TODO(annagrin): Remove the condition after the bogus warning is
     // removed in dwds: https://github.com/dart-lang/webdev/issues/1722
     if (!event.message.contains('No module for')) {

packages/flutter_tools/lib/src/localizations/gen_l10n.dart

@@ -617,8 +617,7 @@ class LocalizationsGenerator {
   /// locales, the difference is negligible, and might slow down the start up
   /// compared to bundling the localizations with the rest of the application.
   ///
-  /// Note that this flag does not affect other platforms such as mobile or
+  /// This flag does not affect other platforms such as mobile or desktop.
-  /// desktop.
   final bool useDeferredLoading;
 
   /// Contains a map of each output language file to its corresponding content in

packages/flutter_tools/lib/src/localizations/message_parser.dart

@@ -492,23 +492,24 @@ class Parser {
     ST.other: 'other',
   };
 
-  // Compress the syntax tree. Note that after
+  // Compress the syntax tree.
-  // parse(lex(message)), the individual parts (ST.string, ST.placeholderExpr,
-  // ST.pluralExpr, and ST.selectExpr) are structured as a linked list See diagram
-  // below. This
-  // function compresses these parts into a single children array (and does this
-  // for ST.pluralParts and ST.selectParts as well). Then it checks extra syntax
-  // rules. Essentially, it converts
   //
-  //            Message
+  // After `parse(lex(message))`, the individual parts (`ST.string`,
-  //            /     \
+  // `ST.placeholderExpr`, `ST.pluralExpr`, and `ST.selectExpr`) are structured
-  //    PluralExpr  Message
+  // as a linked list (see diagram below). This function compresses these parts
-  //                /     \
+  // into a single children array (and does this for `ST.pluralParts` and
-  //            String  Message
+  // `ST.selectParts` as well). Then it checks extra syntax rules. Essentially, it
-  //                    /     \
+  // converts:
-  //            SelectExpr   ...
   //
-  // to
+  //             Message
+  //             /     \
+  //     PluralExpr  Message
+  //                 /     \
+  //             String  Message
+  //                     /     \
+  //             SelectExpr   ...
+  //
+  // ...to:
   //
   //                Message
   //               /   |   \

packages/flutter_tools/lib/src/macos/build_macos.dart

@@ -24,8 +24,10 @@ import 'migrations/remove_macos_framework_link_and_embedding_migration.dart';
 /// Passing this regexp to trace moves the stdout output to stderr.
 ///
 /// Filter out xcodebuild logging unrelated to macOS builds:
+/// ```
 /// xcodebuild[2096:1927385] Requested but did not find extension point with identifier Xcode.IDEKit.ExtensionPointIdentifierToBundleIdentifier for extension Xcode.DebuggerFoundation.AppExtensionToBundleIdentifierMap.watchOS of plug-in com.apple.dt.IDEWatchSupportCore
 /// note: Using new build system
+/// ```
 final RegExp _filteredOutput = RegExp(r'^((?!Requested but did not find extension point with identifier|note\:).)*$');
 
 /// Builds the macOS project through xcodebuild.

packages/flutter_tools/lib/src/reporting/usage.dart

@@ -51,7 +51,7 @@ abstract class Usage {
 
   /// Sends a 'command' to the underlying analytics implementation.
   ///
-  /// Note that using [command] above is preferred to ensure that the parameter
+  /// Using [command] above is preferred to ensure that the parameter
   /// keys are well-defined in [CustomDimensions] above.
   void sendCommand(
     String command, {
@@ -60,8 +60,8 @@ abstract class Usage {
 
   /// Sends an 'event' to the underlying analytics implementation.
   ///
-  /// Note that this method should not be used directly, instead see the
+  /// This method should not be used directly, instead see the
-  /// event types defined in this directory in events.dart.
+  /// event types defined in this directory in `events.dart`.
   @visibleForOverriding
   @visibleForTesting
   void sendEvent(

packages/flutter_tools/lib/src/test/flutter_platform.dart

@@ -121,7 +121,7 @@ FlutterPlatform installHook({
 /// The [integrationTest] argument can be specified to generate the bootstrap
 /// for integration tests.
 ///
-// NOTE: this API is used by the fuchsia source tree, do not add new
+// This API is used by the Fuchsia source tree, do not add new
 // required or position parameters.
 String generateTestBootstrap({
   required Uri testUrl,

packages/flutter_tools/lib/src/web/chrome.dart

@@ -174,7 +174,7 @@ class ChromiumLauncher {
     final String chromeExecutable = _browserFinder(_platform, _fileSystem);
 
     if (_logger.isVerbose && !_platform.isWindows) {
-      // Note: --version is not supported on windows.
+      // The "--version" argument is not supported on Windows.
       final ProcessResult versionResult = await _processManager.run(<String>[chromeExecutable, '--version']);
       _logger.printTrace('Using ${versionResult.stdout}');
     }
@@ -332,7 +332,7 @@ class ChromiumLauncher {
   /// Copy Chrome user information from a Chrome session into a per-project
   /// cache.
   ///
-  /// Note: more detailed docs of the Chrome user preferences store exists here:
+  /// More detailed docs of the Chrome user preferences store exists here:
   /// https://www.chromium.org/developers/design-documents/preferences.
   ///
   /// This intentionally skips the Cache, Code Cache, and GPUCache directories.
@@ -419,9 +419,13 @@ class ChromiumLauncher {
 
   /// Gets the first [chrome] tab.
   ///
-  /// Note: Retry getting tabs from Chrome for a few seconds and retry finding
+  /// Retries getting tabs from Chrome for a few seconds and retries finding
-  /// the tab a few times. This prevents flakes caused by Chrome not returning
+  /// the tab a few times. This reduces flakes caused by Chrome not returning
   /// correct output if the call was too close to the start.
+  //
+  // TODO(ianh): remove the timeouts here, they violate our style guide.
+  // (We should just keep waiting forever, and print a warning when it's
+  // taking too long.)
   Future<ChromeTab?> _getFirstTab(Chromium chrome) async {
     const Duration retryFor = Duration(seconds: 2);
     const int attempts = 5;

packages/flutter_tools/test/general.shard/android/gradle_errors_test.dart

@@ -808,9 +808,9 @@ assembleProfile
           '│   }                                                                                           │\n'
           '│ }                                                                                             │\n'
           '│                                                                                               │\n'
-          "│ Note that your app won't be available to users running Android SDKs below 19.                 │\n"
+          '│ Following this change, your app will not be available to users running Android SDKs below 19. │\n'
-          '│ Alternatively, try to find a version of this plugin that supports these lower versions of the │\n'
+          '│ Consider searching for a version of this plugin that supports these lower versions of the     │\n'
-          '│ Android SDK.                                                                                  │\n'
+          '│ Android SDK instead.                                                                          │\n'
           '│ For more information, see:                                                                    │\n'
           '│ https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration          │\n'
           '└───────────────────────────────────────────────────────────────────────────────────────────────┘\n'

packages/flutter_tools/test/general.shard/macos/cocoapods_test.dart

@@ -458,6 +458,7 @@ void main() {
             'LANG': 'en_US.UTF-8',
           },
           exitCode: 1,
+          // This output is the output that a real CocoaPods install would generate.
           stdout: '''
 [!] Unable to satisfy the following requirements:
 
@@ -481,8 +482,7 @@ Note: as of CocoaPods 1.0, `pod repo update` does not happen on `pod install` by
       ), throwsToolExit());
       expect(
         logger.errorText,
-        contains(
+        contains("CocoaPods's specs repository is too out-of-date to satisfy dependencies"),
-            "CocoaPods's specs repository is too out-of-date to satisfy dependencies"),
       );
     });
 

packages/flutter_tools/test/general.shard/resident_runner_test.dart

@@ -2465,8 +2465,8 @@ flutter:
   }));
 }
 
-// NOTE: implements [dds.DartDevelopmentService] and NOT [DartDevelopmentService]
+// This implements [dds.DartDevelopmentService], not the [DartDevelopmentService]
-// from package:flutter_tools.
+// interface from package:flutter_tools.
 class FakeDartDevelopmentService extends Fake implements dds.DartDevelopmentService {
   @override
   Future<void> get done => Future<void>.value();

packages/flutter_tools/test/integration.shard/test_driver.dart

@@ -275,13 +275,13 @@ abstract class FlutterTestDriver {
   ///
   /// Returns a future that completes when the [kind] event is received.
   ///
-  /// Note that this method should be called before the command that triggers
+  /// This method should be called before the command that triggers
   /// the event to subscribe to the event in time, for example:
   ///
-  /// ```
+  /// ```dart
-  ///  var event = subscribeToDebugEvent('Pause', id); // Subscribe to 'pause' events.
+  /// var event = subscribeToDebugEvent('Pause', id); // Subscribe to 'pause' events.
-  ///  ...                                             // Code that pauses the app.
+  /// ...                                             // Code that pauses the app.
-  ///  await waitForDebugEvent('Pause', id, event);    // Isolate is paused now.
+  /// await waitForDebugEvent('Pause', id, event);    // Isolate is paused now.
   /// ```
   Future<Event> subscribeToDebugEvent(String kind, String isolateId) {
     _debugPrint('Start listening for $kind events');