From 6205c110d64351610219d48b52a1a1b9e0140dcd Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Fri, 17 Feb 2023 14:27:33 -0800 Subject: [PATCH] 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 --- .../complex_layout/lib/src/app.dart | 2 +- .../lib/foundation/platform_asset_bundle.dart | 2 +- .../multiple_flutters/android/build.gradle | 4 +-- dev/bots/analyze.dart | 5 +-- dev/bots/docs.sh | 2 +- dev/ci/README.md | 2 +- dev/conductor/core/lib/src/repository.dart | 3 +- dev/conductor/core/test/start_test.dart | 2 +- .../lib/gallery/example_code.dart | 3 +- .../ios_add2app/FullScreenViewController.m | 4 +-- .../Host/FullScreenViewController.m | 4 +-- .../ios_host_app/flutterapp/lib/main | 6 ++-- .../gen_keycodes/lib/physical_key_data.dart | 7 +++-- .../focus_traversal_group.0.dart | 2 +- .../shared_app_data/shared_app_data.0.dart | 4 +-- .../gesture_detector.2_test.dart | 2 +- examples/layers/raw/canvas.dart | 28 ++++++++--------- packages/flutter/lib/fix_data/README.md | 8 ++--- .../flutter/lib/src/cupertino/refresh.dart | 2 +- .../flutter/lib/src/gestures/resampler.dart | 3 +- .../flutter/lib/src/material/button_bar.dart | 15 +++++---- packages/flutter/lib/src/material/dialog.dart | 28 ++++++++--------- .../lib/src/material/expansion_panel.dart | 25 +++++++++------ .../lib/src/material/expansion_tile.dart | 20 ++++++------ .../lib/src/material/input_decorator.dart | 12 +++---- .../flutter/lib/src/material/list_tile.dart | 2 +- .../flutter/lib/src/material/popup_menu.dart | 2 +- packages/flutter/lib/src/material/tabs.dart | 10 +++--- .../flutter/lib/src/material/text_theme.dart | 6 ++-- .../flutter/lib/src/material/theme_data.dart | 9 +++--- .../flutter/lib/src/painting/borders.dart | 22 ++++++++++--- .../flutter/lib/src/painting/decoration.dart | 6 ++-- .../lib/src/services/asset_manifest.dart | 2 +- .../lib/src/services/raw_keyboard.dart | 4 +-- .../flutter/lib/src/widgets/drag_target.dart | 2 +- .../widgets/draggable_scrollable_sheet.dart | 4 +-- .../lib/src/widgets/focus_manager.dart | 2 +- .../lib/src/widgets/gesture_detector.dart | 10 +++--- .../lib/src/widgets/widget_inspector.dart | 4 +-- .../floating_action_button_location_test.dart | 2 +- .../material/paginated_data_table_test.dart | 2 +- .../flutter/test/material/scaffold_test.dart | 4 +-- .../flutter/test/widgets/semantics_test.dart | 2 +- packages/flutter/test_fixes/README.md | 8 ++--- .../test_fixes/material/app_bar_theme.dart | 2 +- .../lib/src/driver/profiling_summarizer.dart | 2 +- .../lib/src/extension/extension.dart | 4 +-- .../flutter_test/lib/src/widget_tester.dart | 24 +++++++++++++- packages/flutter_tools/bin/podhelper.rb | 8 ++--- .../gradle/app_plugin_loader.gradle | 2 +- packages/flutter_tools/gradle/flutter.gradle | 7 ++--- .../gradle/module_plugin_loader.gradle | 2 +- .../lib/src/android/gradle_errors.dart | 4 +-- .../flutter_tools/lib/src/base/config.dart | 2 +- .../lib/src/build_system/build_system.dart | 2 +- .../lib/src/build_system/targets/common.dart | 2 +- .../lib/src/commands/build_aar.dart | 5 ++- .../lib/src/custom_devices/custom_device.dart | 8 ++--- packages/flutter_tools/lib/src/device.dart | 2 +- .../lib/src/fuchsia/fuchsia_device.dart | 4 +-- .../lib/src/ios/xcode_build_settings.dart | 2 +- .../lib/src/isolated/devfs_web.dart | 2 +- .../lib/src/localizations/gen_l10n.dart | 3 +- .../lib/src/localizations/message_parser.dart | 31 ++++++++++--------- .../lib/src/macos/build_macos.dart | 2 ++ .../lib/src/reporting/usage.dart | 6 ++-- .../lib/src/test/flutter_platform.dart | 2 +- .../flutter_tools/lib/src/web/chrome.dart | 12 ++++--- .../android/gradle_errors_test.dart | 6 ++-- .../general.shard/macos/cocoapods_test.dart | 4 +-- .../general.shard/resident_runner_test.dart | 4 +-- .../test/integration.shard/test_driver.dart | 10 +++--- 72 files changed, 256 insertions(+), 206 deletions(-) diff --git a/dev/benchmarks/complex_layout/lib/src/app.dart b/dev/benchmarks/complex_layout/lib/src/app.dart index 7337d7806770..84a1eb3c2cb6 100644 --- a/dev/benchmarks/complex_layout/lib/src/app.dart +++ b/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( diff --git a/dev/benchmarks/microbenchmarks/lib/foundation/platform_asset_bundle.dart b/dev/benchmarks/microbenchmarks/lib/foundation/platform_asset_bundle.dart index 8d0ed1e7e750..4f2b172a10cd 100644 --- a/dev/benchmarks/microbenchmarks/lib/foundation/platform_asset_bundle.dart +++ b/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; diff --git a/dev/benchmarks/multiple_flutters/android/build.gradle b/dev/benchmarks/multiple_flutters/android/build.gradle index 234d847ee4c3..2118aa0187b6 100644 --- a/dev/benchmarks/multiple_flutters/android/build.gradle +++ b/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 - // in the individual module build.gradle files + // Do not place your application dependencies here; they belong + // in the individual module build.gradle files. } } diff --git a/dev/bots/analyze.dart b/dev/bots/analyze.dart index df185c8e158d..b76ba681f3a9 100644 --- a/dev/bots/analyze.dart +++ b/dev/bots/analyze.dart @@ -1842,7 +1842,7 @@ Future 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 verifyTabooDocumentation(String workingDirectory, { int minimumMatches = 100 }) async { final List errors = []; @@ -1859,7 +1859,8 @@ Future verifyTabooDocumentation(String workingDirectory, { int minimumMatc if (errors.isNotEmpty) { foundError([ '${bold}Avoid the word "simply" in documentation. See https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#use-the-passive-voice-recommend-do-not-require-never-say-things-are-simple for details.$reset', - '${bold}In many cases the word can be omitted without loss of generality; in other cases it may require a bit of rewording to avoid implying that the task is simple.$reset', + '${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, ]); } diff --git a/dev/bots/docs.sh b/dev/bots/docs.sh index f45fc82fb05a..af7847a08981 100755 --- a/dev/bots/docs.sh +++ b/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 diff --git a/dev/ci/README.md b/dev/ci/README.md index 546bc4fecbcd..08f8d7829361 100644 --- a/dev/ci/README.md +++ b/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) diff --git a/dev/conductor/core/lib/src/repository.dart b/dev/conductor/core/lib/src/repository.dart index 0dc55560e5bf..525ef92614d8 100644 --- a/dev/conductor/core/lib/src/repository.dart +++ b/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 - // detached HEAD state. + // If [initialRef] is a remote ref, the checkout will be left in a detached HEAD state. await git.run( ['checkout', initialRef!], 'Checking out initialRef $initialRef', diff --git a/dev/conductor/core/test/start_test.dart b/dev/conductor/core/test/start_test.dart index 7939b5614b72..d1d9d3cd4e06 100644 --- a/dev/conductor/core/test/start_test.dart +++ b/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'; diff --git a/dev/integration_tests/flutter_gallery/lib/gallery/example_code.dart b/dev/integration_tests/flutter_gallery/lib/gallery/example_code.dart index dd8ec56b2d0f..dbbbaea30a4a 100644 --- a/dev/integration_tests/flutter_gallery/lib/gallery/example_code.dart +++ b/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 -// gallery. +// This code is not runnable, it contains code snippets displayed in the Gallery. import 'package:flutter/material.dart'; diff --git a/dev/integration_tests/ios_add2app_life_cycle/ios_add2app/FullScreenViewController.m b/dev/integration_tests/ios_add2app_life_cycle/ios_add2app/FullScreenViewController.m index 3bb392aaa930..ec4035ecf7c4 100644 --- a/dev/integration_tests/ios_add2app_life_cycle/ios_add2app/FullScreenViewController.m +++ b/dev/integration_tests/ios_add2app_life_cycle/ios_add2app/FullScreenViewController.m @@ -22,9 +22,9 @@ -(void)viewWillDisappear:(BOOL)animated { 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. diff --git a/dev/integration_tests/ios_host_app/Host/FullScreenViewController.m b/dev/integration_tests/ios_host_app/Host/FullScreenViewController.m index 3bb392aaa930..ec4035ecf7c4 100644 --- a/dev/integration_tests/ios_host_app/Host/FullScreenViewController.m +++ b/dev/integration_tests/ios_host_app/Host/FullScreenViewController.m @@ -22,9 +22,9 @@ -(void)viewWillDisappear:(BOOL)animated { 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. diff --git a/dev/integration_tests/ios_host_app/flutterapp/lib/main b/dev/integration_tests/ios_host_app/flutterapp/lib/main index c00de68108cb..2f5c09d11b73 100644 --- a/dev/integration_tests/ios_host_app/flutterapp/lib/main +++ b/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 -/// navigation channel, as that never gets propagated back to Flutter after the -/// initial call. +/// We shouldn't use the `setInitialRoute` method on the system +/// navigation channel, as that never gets propagated back to Flutter +/// after the initial call. const String _kReloadChannelName = 'reload'; const BasicMessageChannel _kReloadChannel = BasicMessageChannel(_kReloadChannelName, StringCodec()); diff --git a/dev/tools/gen_keycodes/lib/physical_key_data.dart b/dev/tools/gen_keycodes/lib/physical_key_data.dart index aef81d0d673c..8bc7065ea8c0 100644 --- a/dev/tools/gen_keycodes/lib/physical_key_data.dart +++ b/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> _readAndroidScanCodes(String keyboardLayout, String nameMap) { final RegExp keyEntry = RegExp( diff --git a/examples/api/lib/widgets/focus_traversal/focus_traversal_group.0.dart b/examples/api/lib/widgets/focus_traversal/focus_traversal_group.0.dart index 55ac18cd03a7..cf9770a08149 100644 --- a/examples/api/lib/widgets/focus_traversal/focus_traversal_group.0.dart +++ b/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 diff --git a/examples/api/lib/widgets/shared_app_data/shared_app_data.0.dart b/examples/api/lib/widgets/shared_app_data/shared_app_data.0.dart index 513f3dcaf106..8063eab76384 100644 --- a/examples/api/lib/widgets/shared_app_data/shared_app_data.0.dart +++ b/examples/api/lib/widgets/shared_app_data/shared_app_data.0.dart @@ -52,7 +52,7 @@ class _HomeState extends State { _fooVersion += 1; // Changing the SharedAppData's value for 'foo' causes the // widgets that depend on 'foo' to be rebuilt. - SharedAppData.setValue(context, 'foo', 'FOO $_fooVersion'); // note: no setState() + SharedAppData.setValue(context, 'foo', 'FOO $_fooVersion'); // no need to call setState() }, ), const SizedBox(height: 16), @@ -60,7 +60,7 @@ class _HomeState extends State { child: const Text('change bar'), onPressed: () { _barVersion += 1; - SharedAppData.setValue(context, 'bar', 'BAR $_barVersion'); // note: no setState() + SharedAppData.setValue(context, 'bar', 'BAR $_barVersion'); // no need to call setState() }, ), ], diff --git a/examples/api/test/widgets/gesture_detector/gesture_detector.2_test.dart b/examples/api/test/widgets/gesture_detector/gesture_detector.2_test.dart index 5b03efa9854e..eb59b902eb87 100644 --- a/examples/api/test/widgets/gesture_detector/gesture_detector.2_test.dart +++ b/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(innerGestureDetectorFinder); expect(innerGestureDetector.behavior, behavior); diff --git a/examples/layers/raw/canvas.dart b/examples/layers/raw/canvas.dart index 3852984a0118..c98c48af6c41 100644 --- a/examples/layers/raw/canvas.dart +++ b/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 - // yellow-bluish rectangle + // Transforms that occur after this point apply only to the + // 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) { [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 - // yellow circle + // Transforms that occur after this point apply only to the + // yellow circle. // Scale x and y by 0.5. final Float64List scaleMatrix = Float64List.fromList([ @@ -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 - // the rectangle and smaller circle + // This circle is drawn on top of the previous layer that contains + // 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 diff --git a/packages/flutter/lib/fix_data/README.md b/packages/flutter/lib/fix_data/README.md index 95358ba378a8..dc7587800992 100644 --- a/packages/flutter/lib/fix_data/README.md +++ b/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 -repositories. Specifically, the CI system for the dart-lang/sdk repo runs these -tests in order to ensure that changes to the dart fix file format do not break -Flutter. +The tests in this directory are also invoked from external +repositories. Specifically, the CI system for the dart-lang/sdk repo +runs these tests in order to ensure that changes to the dart fix file +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. diff --git a/packages/flutter/lib/src/cupertino/refresh.dart b/packages/flutter/lib/src/cupertino/refresh.dart index b9e528c43669..87fbbd5704a4 100644 --- a/packages/flutter/lib/src/cupertino/refresh.dart +++ b/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( diff --git a/packages/flutter/lib/src/gestures/resampler.dart b/packages/flutter/lib/src/gestures/resampler.dart index aa367257ca27..e2a67e0739a4 100644 --- a/packages/flutter/lib/src/gestures/resampler.dart +++ b/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) { diff --git a/packages/flutter/lib/src/material/button_bar.dart b/packages/flutter/lib/src/material/button_bar.dart index 7cdd64ac69c5..f1fef7b43919 100644 --- a/packages/flutter/lib/src/material/button_bar.dart +++ b/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 - /// arranged into a column. This parameter provides additional - /// vertical space in between buttons when it does overflow. + /// If the [children] do not fit into a single row, they are arranged into a + /// column. This parameter provides additional vertical space in between + /// buttons when it does overflow. /// - /// Note that the button spacing may appear to be more than - /// the value provided. This is because most buttons adhere to the - /// [MaterialTapTargetSize] of 48px. So, even though a button - /// might visually be 36px in height, it might still take up to - /// 48px vertically. + /// The button spacing may appear to be more than the value provided. This is + /// because most buttons adhere to the [MaterialTapTargetSize] of 48px. So, + /// even though a button might visually be 36px in height, it might still take + /// up to 48px vertically. /// /// If null then no spacing will be added in between buttons in /// an overflow state. diff --git a/packages/flutter/lib/src/material/dialog.dart b/packages/flutter/lib/src/material/dialog.dart index 900e832128f8..d414c44e2e7a 100644 --- a/packages/flutter/lib/src/material/dialog.dart +++ b/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 - /// important to note that [buttonPadding] may contribute to the padding on - /// the edges of [actions] as well. + /// The [buttonPadding] may contribute to the padding on 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 - /// to a column layout because the actions don't fit horizontally. + /// The spacing between [actions] when the [OverflowBar] switches to a column + /// 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 - /// vertical space in between buttons when it does overflow. + /// arranged into a column. This parameter provides additional vertical space + /// between buttons when it does overflow. /// - /// Note that the button spacing may appear to be more than - /// the value provided. This is because most buttons adhere to the - /// [MaterialTapTargetSize] of 48px. So, even though a button - /// might visually be 36px in height, it might still take up to - /// 48px vertically. + /// The button spacing may appear to be more than the value provided. This is + /// because most buttons adhere to the [MaterialTapTargetSize] of 48px. So, + /// even though a button might visually be 36px in height, it might still take + /// up to 48px vertically. /// - /// If null then no spacing will be added in between buttons in - /// an overflow state. + /// If null then no spacing will be added in between buttons in an overflow + /// state. final double? actionsOverflowButtonSpacing; /// The padding that surrounds each button in [actions]. diff --git a/packages/flutter/lib/src/material/expansion_panel.dart b/packages/flutter/lib/src/material/expansion_panel.dart index bfacb0cca5e9..53dedceb9e08 100644 --- a/packages/flutter/lib/src/material/expansion_panel.dart +++ b/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] -/// and [ExpansionPanelList.radio]. +/// The [expansionCallback] is called when the expansion state changes. For +/// 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] -/// * [ExpansionPanelList.radio] +/// * [ExpansionPanel], which is used in the [children] property. +/// * [ExpansionPanelList.radio], a variant of this widget where only one panel is open at a time. /// * 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 - /// about the closing/opening panel. On the other hand, the callback for - /// [ExpansionPanelList.radio] is intended to inform the parent widget of - /// changes, as the radio panels' open/close states are managed internally. + /// For [ExpansionPanelList], the callback should call [State.setState] when + /// it is notified about the closing/opening panel. On the other hand, the + /// callback for [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 /// panels in a parent widget that may need to react to these changes. diff --git a/packages/flutter/lib/src/material/expansion_tile.dart b/packages/flutter/lib/src/material/expansion_tile.dart index 89da3dce55a7..0f19918e7cd3 100644 --- a/packages/flutter/lib/src/material/expansion_tile.dart +++ b/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 - /// [children] will be the same as the widest child widget in [children]. It is - /// not necessarily the width of [Column] is equal to the width of expanded tile. + /// within its [Column]. The width of the [Column] that houses [children] will + /// be the same as the widest child widget in [children]. The width of the + /// [Column] might not be equal to the width of the expanded tile. /// - /// To align the [Column] along the expanded tile, use the [expandedAlignment] property - /// instead. + /// To align the [Column] along the expanded tile, use the [expandedAlignment] + /// 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]. diff --git a/packages/flutter/lib/src/material/input_decorator.dart b/packages/flutter/lib/src/material/input_decorator.dart index 411edf0c0c01..3e6d698a173b 100644 --- a/packages/flutter/lib/src/material/input_decorator.dart +++ b/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 - /// style. + /// an example of how to replicate this behavior when specifying those + /// 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 diff --git a/packages/flutter/lib/src/material/list_tile.dart b/packages/flutter/lib/src/material/list_tile.dart index e881745d65a7..030626e6b56d 100644 --- a/packages/flutter/lib/src/material/list_tile.dart +++ b/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 diff --git a/packages/flutter/lib/src/material/popup_menu.dart b/packages/flutter/lib/src/material/popup_menu.dart index 2249d99f10fe..c22b0b8d0f83 100644 --- a/packages/flutter/lib/src/material/popup_menu.dart +++ b/packages/flutter/lib/src/material/popup_menu.dart @@ -251,7 +251,7 @@ class PopupMenuItem extends PopupMenuEntry { /// 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. /// diff --git a/packages/flutter/lib/src/material/tabs.dart b/packages/flutter/lib/src/material/tabs.dart index 5fb8fc7a8adc..c488a4ee7539 100644 --- a/packages/flutter/lib/src/material/tabs.dart +++ b/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 - /// affect the effective [labelColor]. + /// The color specified in the [labelStyle] and the [TabBarTheme.labelStyle] + /// 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 - /// [TabBarTheme.unselectedLabelStyle]'s color are ignored in - /// [unselectedLabelColor]'s precedence calculation. + /// The color specified in the [unselectedLabelStyle] and the + /// [TabBarTheme.unselectedLabelStyle] are ignored in [unselectedLabelColor]'s + /// precedence calculation. /// /// See also: /// diff --git a/packages/flutter/lib/src/material/text_theme.dart b/packages/flutter/lib/src/material/text_theme.dart index fed7a2f9075a..6d1363b3bbdb 100644 --- a/packages/flutter/lib/src/material/text_theme.dart +++ b/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 - /// styles. Only one or the other is allowed in this constructor. The 2018 - /// styles will be deprecated and removed eventually. + /// The 2018 styles cannot be mixed with the 2021 styles. Only one or the + /// other is allowed in this constructor. The 2018 styles are deprecated and + /// will eventually be removed. const TextTheme({ TextStyle? displayLarge, TextStyle? displayMedium, diff --git a/packages/flutter/lib/src/material/theme_data.dart b/packages/flutter/lib/src/material/theme_data.dart index 9af3972cefc8..0f8ed6dc9a88 100644 --- a/packages/flutter/lib/src/material/theme_data.dart +++ b/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 - /// [ThemeData.copyWith] with [useMaterial3] set to true will - /// not change any of these properties in the resulting [ThemeData]. + /// + /// If a [ThemeData] is _constructed_ with [useMaterial3] set to true, then + /// some properties will get updated defaults. However, the + /// [ThemeData.copyWith] method with [useMaterial3] set to true will _not_ + /// change any of these properties in the resulting [ThemeData]. /// /// /// diff --git a/packages/flutter/lib/src/painting/borders.dart b/packages/flutter/lib/src/painting/borders.dart index e1100cb54738..66744283d15e 100644 --- a/packages/flutter/lib/src/painting/borders.dart +++ b/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 -/// rendering. A more involved explanation is present in [BorderSide.width]. +/// Setting [BorderSide.width] to 0.0 will result in hairline rendering; see +/// [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. diff --git a/packages/flutter/lib/src/painting/decoration.dart b/packages/flutter/lib/src/painting/decoration.dart index 2a52c0385dc6..efc9bfdb6330 100644 --- a/packages/flutter/lib/src/painting/decoration.dart +++ b/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 diff --git a/packages/flutter/lib/src/services/asset_manifest.dart b/packages/flutter/lib/src/services/asset_manifest.dart index cddf7984f85a..4de568ad7569 100644 --- a/packages/flutter/lib/src/services/asset_manifest.dart +++ b/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 diff --git a/packages/flutter/lib/src/services/raw_keyboard.dart b/packages/flutter/lib/src/services/raw_keyboard.dart index 35985390510e..a36f0de6dd03 100644 --- a/packages/flutter/lib/src/services/raw_keyboard.dart +++ b/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. diff --git a/packages/flutter/lib/src/widgets/drag_target.dart b/packages/flutter/lib/src/widgets/drag_target.dart index f89cd6aaab27..3f3362b347de 100644 --- a/packages/flutter/lib/src/widgets/drag_target.dart +++ b/packages/flutter/lib/src/widgets/drag_target.dart @@ -648,7 +648,7 @@ class DragTarget 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? onMove; /// How to behave during hit testing. diff --git a/packages/flutter/lib/src/widgets/draggable_scrollable_sheet.dart b/packages/flutter/lib/src/widgets/draggable_scrollable_sheet.dart index d586e2684ace..a273d9b051bb 100644 --- a/packages/flutter/lib/src/widgets/draggable_scrollable_sheet.dart +++ b/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 - /// started after this one finished so `onCanceled` should be safe to call at + /// The `onCanceled` callback will get called even if the subsequent activity + /// started after this one finished, so `onCanceled` must be safe to call at /// any time. void startActivity({required VoidCallback onCanceled}) { _cancelActivity?.call(); diff --git a/packages/flutter/lib/src/widgets/focus_manager.dart b/packages/flutter/lib/src/widgets/focus_manager.dart index de94e41cf3e8..c9879dd43079 100644 --- a/packages/flutter/lib/src/widgets/focus_manager.dart +++ b/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')); diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart index a0f5261e9531..f27f5b1a3d01 100644 --- a/packages/flutter/lib/src/widgets/gesture_detector.dart +++ b/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; diff --git a/packages/flutter/lib/src/widgets/widget_inspector.dart b/packages/flutter/lib/src/widgets/widget_inspector.dart index 1ee8953bd167..76ade9b23046 100644 --- a/packages/flutter/lib/src/widgets/widget_inspector.dart +++ b/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 to work correctly. +/// Tracking will not work correctly if the function has optional positional +/// parameters. /// /// Currently this annotation is only supported on extension methods. /// diff --git a/packages/flutter/test/material/floating_action_button_location_test.dart b/packages/flutter/test/material/floating_action_button_location_test.dart index 161cadd50eac..aebfb8f94406 100644 --- a/packages/flutter/test/material/floating_action_button_location_test.dart +++ b/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 rotationTransitions = tester.widgetList( find.byType(RotationTransition), diff --git a/packages/flutter/test/material/paginated_data_table_test.dart b/packages/flutter/test/material/paginated_data_table_test.dart index 430e83ae6f5c..4f97d771c80c 100644 --- a/packages/flutter/test/material/paginated_data_table_test.dart +++ b/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; diff --git a/packages/flutter/test/material/scaffold_test.dart b/packages/flutter/test/material/scaffold_test.dart index f905d0cfc2d2..5a15ee6c3e04 100644 --- a/packages/flutter/test/material/scaffold_test.dart +++ b/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)); diff --git a/packages/flutter/test/widgets/semantics_test.dart b/packages/flutter/test/widgets/semantics_test.dart index 20b08aedf13a..36a9cb00e483 100644 --- a/packages/flutter/test/widgets/semantics_test.dart +++ b/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'), diff --git a/packages/flutter/test_fixes/README.md b/packages/flutter/test_fixes/README.md index 3b25e3a64d36..38dbb0609261 100644 --- a/packages/flutter/test_fixes/README.md +++ b/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 -repositories. Specifically, the CI system for the dart-lang/sdk repo runs these -tests in order to ensure that changes to the dart fix file format do not break -Flutter. +The tests in this directory are also invoked from external +repositories. Specifically, the CI system for the dart-lang/sdk repo +runs these tests in order to ensure that changes to the dart fix file +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. diff --git a/packages/flutter/test_fixes/material/app_bar_theme.dart b/packages/flutter/test_fixes/material/app_bar_theme.dart index ee890761d179..9195617725ef 100644 --- a/packages/flutter/test_fixes/material/app_bar_theme.dart +++ b/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); diff --git a/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart b/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart index 0ed7dfd29d8c..b3e708a6b886 100644 --- a/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart +++ b/packages/flutter_driver/lib/src/driver/profiling_summarizer.dart @@ -70,7 +70,7 @@ class ProfilingSummarizer { final Map> 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 summarize() { final Map summary = {}; diff --git a/packages/flutter_driver/lib/src/extension/extension.dart b/packages/flutter_driver/lib/src/extension/extension.dart index da0df095df8e..d744b5094d69 100644 --- a/packages/flutter_driver/lib/src/extension/extension.dart +++ b/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. /// diff --git a/packages/flutter_test/lib/src/widget_tester.dart b/packages/flutter_test/lib/src/widget_tester.dart index 517a02564768..e82291c32031 100644 --- a/packages/flutter_test/lib/src/widget_tester.dart +++ b/packages/flutter_test/lib/src/widget_tester.dart @@ -499,12 +499,34 @@ Future 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) { diff --git a/packages/flutter_tools/bin/podhelper.rb b/packages/flutter_tools/bin/podhelper.rb index a24a1f21ec0a..614cb9009a15 100644 --- a/packages/flutter_tools/bin/podhelper.rb +++ b/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 is a generated file; do not edit or check into version control. + # 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. # 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 is a generated file; do not edit or check into version control. + # 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. # Pod::Spec.new do |s| diff --git a/packages/flutter_tools/gradle/app_plugin_loader.gradle b/packages/flutter_tools/gradle/app_plugin_loader.gradle index ed92e8ef7c1d..e5cfe9ca55db 100644 --- a/packages/flutter_tools/gradle/app_plugin_loader.gradle +++ b/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 diff --git a/packages/flutter_tools/gradle/flutter.gradle b/packages/flutter_tools/gradle/flutter.gradle index be7c89804cec..1a104d405a00 100644 --- a/packages/flutter_tools/gradle/flutter.gradle +++ b/packages/flutter_tools/gradle/flutter.gradle @@ -279,9 +279,8 @@ class FlutterPlugin implements Plugin { // Enables code shrinking, obfuscation, and optimization for only // your project's release build type. minifyEnabled true - // Enables resource shrinking, which is performed by the - // Android Gradle plugin. - // NOTE: The resource shrinker can't be used for libraries. + // Enables resource shrinking, which is performed by the Android Gradle plugin. + // 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 { /** * 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). */ diff --git a/packages/flutter_tools/gradle/module_plugin_loader.gradle b/packages/flutter_tools/gradle/module_plugin_loader.gradle index 7f7bebe468bc..2e3a80091499 100644 --- a/packages/flutter_tools/gradle/module_plugin_loader.gradle +++ b/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) diff --git a/packages/flutter_tools/lib/src/android/gradle_errors.dart b/packages/flutter_tools/lib/src/android/gradle_errors.dart index 406984cf626c..e07657d794bb 100644 --- a/packages/flutter_tools/lib/src/android/gradle_errors.dart +++ b/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" - 'Alternatively, try to find a version of this plugin that supports these lower versions of the Android SDK.\n' + 'Following this change, your app will not be available to users running Android SDKs below ${minSdkVersionMatch?.group(2)}.\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, ); diff --git a/packages/flutter_tools/lib/src/base/config.dart b/packages/flutter_tools/lib/src/base/config.dart index 804cef0673f7..2352c862b779 100644 --- a/packages/flutter_tools/lib/src/base/config.dart +++ b/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] ?? '.'; diff --git a/packages/flutter_tools/lib/src/build_system/build_system.dart b/packages/flutter_tools/lib/src/build_system/build_system.dart index c11f25912f33..63b2c78777ba 100644 --- a/packages/flutter_tools/lib/src/build_system/build_system.dart +++ b/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]. /// diff --git a/packages/flutter_tools/lib/src/build_system/targets/common.dart b/packages/flutter_tools/lib/src/build_system/targets/common.dart index 7bd413aa3f19..2e0a0096ea8a 100644 --- a/packages/flutter_tools/lib/src/build_system/targets/common.dart +++ b/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. diff --git a/packages/flutter_tools/lib/src/commands/build_aar.dart b/packages/flutter_tools/lib/src/commands/build_aar.dart index 7a54c7941ce2..c8419f0f2d06 100644 --- a/packages/flutter_tools/lib/src/commands/build_aar.dart +++ b/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 ' - 'https://flutter.dev/go/build-aar\n' - 'Note: this command builds applications assuming that the entrypoint is lib/main.dart. ' + 'To learn more about how to use these artifacts, see: https://flutter.dev/go/build-aar\n' + 'This command assumes that the entrypoint is "lib/main.dart". ' 'This cannot currently be configured.'; @override diff --git a/packages/flutter_tools/lib/src/custom_devices/custom_device.dart b/packages/flutter_tools/lib/src/custom_devices/custom_device.dart index cfbcf9f67c4c..0093d570a38c 100644 --- a/packages/flutter_tools/lib/src/custom_devices/custom_device.dart +++ b/packages/flutter_tools/lib/src/custom_devices/custom_device.dart @@ -166,11 +166,11 @@ class CustomDevicePortForwarder extends DevicePortForwarder { final Completer completer = Completer(); - // 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 - // Note that if that regex never matches, this will potentially run forever - // and the forwarding will never complete + // forwarded port. + // If that regex never matches, this will potentially run forever + // and the forwarding will never complete. final CustomDeviceLogReader reader = CustomDeviceLogReader(_deviceName)..listenToProcessOutput(process); final StreamSubscription logLinesSubscription = reader.logLines.listen((String line) { if (_forwardPortSuccessRegex.hasMatch(line) && !completer.isCompleted) { diff --git a/packages/flutter_tools/lib/src/device.dart b/packages/flutter_tools/lib/src/device.dart index 55ec8dab63e0..276670a2d969 100644 --- a/packages/flutter_tools/lib/src/device.dart +++ b/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 ephemeralDevices = [ for (final Device device in devices) diff --git a/packages/flutter_tools/lib/src/fuchsia/fuchsia_device.dart b/packages/flutter_tools/lib/src/fuchsia/fuchsia_device.dart index 60744d4fbea6..1640f7d23469 100644 --- a/packages/flutter_tools/lib/src/fuchsia/fuchsia_device.dart +++ b/packages/flutter_tools/lib/src/fuchsia/fuchsia_device.dart @@ -696,7 +696,7 @@ class FuchsiaDevice extends Device { Future findIsolatePort(String isolateName, List 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 command = [ 'ssh', diff --git a/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart b/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart index 596e3dee6dcd..2ef75a209de2 100644 --- a/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart +++ b/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart @@ -181,7 +181,7 @@ Future> _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. diff --git a/packages/flutter_tools/lib/src/isolated/devfs_web.dart b/packages/flutter_tools/lib/src/isolated/devfs_web.dart index cdd04e37d6cc..ac2652baa63b 100644 --- a/packages/flutter_tools/lib/src/isolated/devfs_web.dart +++ b/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')) { diff --git a/packages/flutter_tools/lib/src/localizations/gen_l10n.dart b/packages/flutter_tools/lib/src/localizations/gen_l10n.dart index 959ab990024b..5c3538cbc83b 100644 --- a/packages/flutter_tools/lib/src/localizations/gen_l10n.dart +++ b/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 - /// desktop. + /// This flag does not affect other platforms such as mobile or desktop. final bool useDeferredLoading; /// Contains a map of each output language file to its corresponding content in diff --git a/packages/flutter_tools/lib/src/localizations/message_parser.dart b/packages/flutter_tools/lib/src/localizations/message_parser.dart index a7198ef97860..259fc38fe08c 100644 --- a/packages/flutter_tools/lib/src/localizations/message_parser.dart +++ b/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 - // 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 + // Compress the syntax tree. // - // Message - // / \ - // PluralExpr Message - // / \ - // String Message - // / \ - // SelectExpr ... + // After `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: // - // to + // Message + // / \ + // PluralExpr Message + // / \ + // String Message + // / \ + // SelectExpr ... + // + // ...to: // // Message // / | \ diff --git a/packages/flutter_tools/lib/src/macos/build_macos.dart b/packages/flutter_tools/lib/src/macos/build_macos.dart index 9a74f5e47fb7..d28c775601fb 100644 --- a/packages/flutter_tools/lib/src/macos/build_macos.dart +++ b/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. diff --git a/packages/flutter_tools/lib/src/reporting/usage.dart b/packages/flutter_tools/lib/src/reporting/usage.dart index 454554cbd176..ea8d18e54fd1 100644 --- a/packages/flutter_tools/lib/src/reporting/usage.dart +++ b/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 - /// event types defined in this directory in events.dart. + /// This method should not be used directly, instead see the + /// event types defined in this directory in `events.dart`. @visibleForOverriding @visibleForTesting void sendEvent( diff --git a/packages/flutter_tools/lib/src/test/flutter_platform.dart b/packages/flutter_tools/lib/src/test/flutter_platform.dart index b8cc9d532cab..c4f02e06935e 100644 --- a/packages/flutter_tools/lib/src/test/flutter_platform.dart +++ b/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, diff --git a/packages/flutter_tools/lib/src/web/chrome.dart b/packages/flutter_tools/lib/src/web/chrome.dart index b7abbab4a1ad..d7fbcc18a0cd 100644 --- a/packages/flutter_tools/lib/src/web/chrome.dart +++ b/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([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 - /// the tab a few times. This prevents flakes caused by Chrome not returning + /// Retries getting tabs from Chrome for a few seconds and retries finding + /// 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 _getFirstTab(Chromium chrome) async { const Duration retryFor = Duration(seconds: 2); const int attempts = 5; diff --git a/packages/flutter_tools/test/general.shard/android/gradle_errors_test.dart b/packages/flutter_tools/test/general.shard/android/gradle_errors_test.dart index b6549f250049..2b5f89de4b6d 100644 --- a/packages/flutter_tools/test/general.shard/android/gradle_errors_test.dart +++ b/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" - '│ Alternatively, try to find a version of this plugin that supports these lower versions of the │\n' - '│ Android SDK. │\n' + '│ Following this change, your app will not be available to users running Android SDKs below 19. │\n' + '│ Consider searching for a version of this plugin that supports these lower versions of the │\n' + '│ Android SDK instead. │\n' '│ For more information, see: │\n' '│ https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration │\n' '└───────────────────────────────────────────────────────────────────────────────────────────────┘\n' diff --git a/packages/flutter_tools/test/general.shard/macos/cocoapods_test.dart b/packages/flutter_tools/test/general.shard/macos/cocoapods_test.dart index 3c34f14426e7..d29ee82ccb67 100644 --- a/packages/flutter_tools/test/general.shard/macos/cocoapods_test.dart +++ b/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( - "CocoaPods's specs repository is too out-of-date to satisfy dependencies"), + contains("CocoaPods's specs repository is too out-of-date to satisfy dependencies"), ); }); diff --git a/packages/flutter_tools/test/general.shard/resident_runner_test.dart b/packages/flutter_tools/test/general.shard/resident_runner_test.dart index f9c9f61eb448..636e752eb7d0 100644 --- a/packages/flutter_tools/test/general.shard/resident_runner_test.dart +++ b/packages/flutter_tools/test/general.shard/resident_runner_test.dart @@ -2465,8 +2465,8 @@ flutter: })); } -// NOTE: implements [dds.DartDevelopmentService] and NOT [DartDevelopmentService] -// from package:flutter_tools. +// This implements [dds.DartDevelopmentService], not the [DartDevelopmentService] +// interface from package:flutter_tools. class FakeDartDevelopmentService extends Fake implements dds.DartDevelopmentService { @override Future get done => Future.value(); diff --git a/packages/flutter_tools/test/integration.shard/test_driver.dart b/packages/flutter_tools/test/integration.shard/test_driver.dart index 07ed89f685cc..2a6a19f931f3 100644 --- a/packages/flutter_tools/test/integration.shard/test_driver.dart +++ b/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: /// - /// ``` - /// var event = subscribeToDebugEvent('Pause', id); // Subscribe to 'pause' events. - /// ... // Code that pauses the app. - /// await waitForDebugEvent('Pause', id, event); // Isolate is paused now. + /// ```dart + /// var event = subscribeToDebugEvent('Pause', id); // Subscribe to 'pause' events. + /// ... // Code that pauses the app. + /// await waitForDebugEvent('Pause', id, event); // Isolate is paused now. /// ``` Future subscribeToDebugEvent(String kind, String isolateId) { _debugPrint('Start listening for $kind events');