API documentation cleanup (#108500)

dev/bots/analyze.dart

@@ -177,7 +177,7 @@ Future<void> run(List<String> arguments) async {
   // Analyze the code in `{@tool snippet}` sections in the repo.
   print('$clock Snippet code...');
   await runCommand(dart,
-    <String>[path.join(flutterRoot, 'dev', 'bots', 'analyze_snippet_code.dart'), '--verbose'],
+    <String>['--enable-asserts', path.join(flutterRoot, 'dev', 'bots', 'analyze_snippet_code.dart'), '--verbose'],
     workingDirectory: flutterRoot,
   );
 

dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart

@@ -8,28 +8,15 @@
 
 library dart.ui;
 
-/// Annotation used by Flutter's Dart compiler to indicate that an
+/// Bla bla bla bla bla bla bla bla bla.
-/// [Object.toString] override should not be replaced with a supercall.
-///
-/// {@tool snippet}
-/// A sample if using keepToString to prevent replacement by a supercall.
 ///
 /// ```dart
 /// class MyStringBuffer {
-///   error;
+///   error; // error (missing_const_final_var_or_type, always_specify_types)
 ///
-///   StringBuffer _buffer = StringBuffer();
+///   StringBuffer _buffer = StringBuffer(); // error (prefer_final_fields, unused_field)
-///
-///   @keepToString
-///   @override
-///   String toString() {
-///     return _buffer.toString();
-///   }
 /// }
 /// ```
-/// {@end-tool}
+class Foo {
-const Object keepToString = _KeepToString();
+  const Foo();
-
-class _KeepToString {
-  const _KeepToString();
 }

dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart

@@ -8,8 +8,8 @@
 // Examples can assume:
 // bool _visible = true;
 // class _Text extends Text {
-//   const _Text(String text) : super(text);
+//   const _Text(super.text);
-//   const _Text.__(String text) : super(text);
+//   const _Text.__(super.text);
 // }
 
 /// A blabla that blabla its blabla blabla blabla.
@@ -27,7 +27,7 @@
 /// blabla it when it is blabla:
 ///
 /// ```dart
-/// new Opacity(
+/// new Opacity( // error (unnecessary_new)
 ///   opacity: _visible ? 1.0 : 0.0,
 ///   child: const Text('Poor wandering ones!'),
 /// )
@@ -38,12 +38,12 @@
 /// Bla blabla blabla some [Text] when the `_blabla` blabla blabla is true, and
 /// blabla it when it is blabla:
 ///
-/// ```dart preamble
+/// ```dart
-/// bool _visible = true;
 /// final GlobalKey globalKey = GlobalKey();
 /// ```
 ///
 /// ```dart
+/// // continuing from previous example...
 /// Widget build(BuildContext context) {
 ///   return Opacity(
 ///     key: globalKey,
@@ -59,7 +59,7 @@
 /// blabla finale blabla:
 ///
 /// ```dart
-/// new Opacity(
+/// Opacity(
 ///   opacity: _visible ? 1.0 : 0.0,
 ///   child: const Text('Poor wandering ones!'),
 /// )
@@ -92,7 +92,7 @@
 /// const variable
 ///
 /// ```dart
-/// const text0 = Text('Poor wandering ones!');
+/// const Widget text0 = Text('Poor wandering ones!');
 /// ```
 /// {@end-tool}
 ///
@@ -100,7 +100,7 @@
 /// more const variables
 ///
 /// ```dart
-/// const text1 = _Text('Poor wandering ones!');
+/// const text1 = _Text('Poor wandering ones!'); // error (always_specify_types)
 /// ```
 /// {@end-tool}
 ///
@@ -108,35 +108,61 @@
 /// Snippet with null-safe syntax
 ///
 /// ```dart
-/// final String? bar = 'Hello';
+/// final String? bar = 'Hello'; // error (unnecessary_nullable_for_final_variable_declarations, prefer_const_declarations)
-/// final int foo = null;
+/// final int foo = null; // error (invalid_assignment, prefer_const_declarations)
 /// ```
 /// {@end-tool}
 ///
-/// {@tool snippet}
 /// snippet with trailing comma
 ///
 /// ```dart
 /// const SizedBox(),
 /// ```
-/// {@end-tool}
 ///
-/// {@tool snippet}
+/// {@tool dartpad}
 /// Dartpad with null-safe syntax
 ///
-/// ```dart preamble
+/// ```dart
-/// bool? _visible = true;
 /// final GlobalKey globalKey = GlobalKey();
 /// ```
 ///
 /// ```dart
+/// // not continuing from previous example...
 /// Widget build(BuildContext context) {
 ///   final String title;
 ///   return Opacity(
-///     key: globalKey,
+///     key: globalKey, // error (undefined_identifier, argument_type_not_assignable)
-///     opacity: _visible! ? 1.0 : 0.0,
+///     opacity: _visible ? 1.0 : 0.0,
-///     child: Text(title),
+///     child: Text(title), // error (read_potentially_unassigned_final)
 ///   );
 /// }
 /// ```
 /// {@end-tool}
+///
+/// ```csv
+/// this,is,fine
+/// ```
+///
+/// ```dart
+/// import 'dart:io'; // error (unused_import)
+/// final Widget p = Placeholder(); // error (undefined_class, undefined_function, avoid_dynamic_calls)
+/// ```
+///
+/// ```dart
+/// // (e.g. in a stateful widget)
+/// void initState() { // error (must_call_super, annotate_overrides)
+///   widget.toString(); // error (undefined_identifier, return_of_invalid_type)
+/// }
+/// ```
+///
+/// ```dart
+/// // not in a stateful widget
+/// void initState() {
+///   widget.toString(); // error (undefined_identifier)
+/// }
+/// ```
+///
+/// ```
+/// error (something about backticks)
+/// this must be the last error, since it aborts parsing of this file
+/// ```

dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart

@@ -0,0 +1,17 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// This file is used by ../analyze_snippet_code_test.dart, which depends on the
+// precise contents (including especially the comments) of this file.
+
+// Examples can assume:
+// int x = ''; // error (invalid_assignment)
+
+/// ```dart
+/// print(x);
+/// ```
+
+/// error: empty dart block
+/// ```dart
+/// ```

dev/bots/test/analyze_snippet_code_test.dart

@@ -2,10 +2,43 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// we ignore these so that the format of the strings below matches what package:test prints, to make maintenance easier
+// ignore_for_file: avoid_escaping_inner_quotes
+// ignore_for_file: use_raw_strings
+
 import 'dart:io';
 
 import 'common.dart';
 
+const List<String> expectedMainErrors = <String>[
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:30:5: Unnecessary new keyword (expression) (unnecessary_new)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:103:5: Specify type annotations (statement) (always_specify_types)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:5: Prefer const over final for declarations (top-level declaration) (prefer_const_declarations)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:19: Use a non-nullable type for a final variable initialized with a non-nullable value (top-level declaration) (unnecessary_nullable_for_final_variable_declarations)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:5: Prefer const over final for declarations (top-level declaration) (prefer_const_declarations)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:21: A value of type \'Null\' can\'t be assigned to a variable of type \'int\' (top-level declaration) (invalid_assignment)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:134:14: The argument type \'dynamic\' can\'t be assigned to the parameter type \'Key?\' (top-level declaration) (argument_type_not_assignable)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:134:14: Undefined name \'globalKey\' (top-level declaration) (undefined_identifier)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:136:21: The final variable \'title\' can\'t be read because it\'s potentially unassigned at this point (top-level declaration) (read_potentially_unassigned_final)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:147:12: Unused import: \'dart:io\' (self-contained program) (unused_import)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:11: Undefined class \'Widget\' (self-contained program) (undefined_class)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:22: Avoid method calls or property accesses on a "dynamic" target (self-contained program) (avoid_dynamic_calls)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:22: The function \'Placeholder\' isn\'t defined (self-contained program) (undefined_function)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:153:10: Annotate overridden members (stateful widget) (annotate_overrides)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:153:10: This method overrides a method annotated as \'@mustCallSuper\' in \'State\', but doesn\'t invoke the overridden method (stateful widget) (must_call_super)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:161:7: Undefined name \'widget\' (top-level declaration) (undefined_identifier)',
+  'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:165: Found "```" in code but it did not match RegExp: pattern=^ */// *```dart\$ flags= so something is wrong. Line was: "/// ```"',
+  'dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart:9:12: A value of type \'String\' can\'t be assigned to a variable of type \'int\' (statement) (invalid_assignment)',
+  'dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart:17:4: Empty ```dart block in snippet code.',
+];
+
+const List<String> expectedUiErrors = <String>[
+  'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:15:7: Prefer typing uninitialized variables and fields (top-level declaration) (prefer_typing_uninitialized_variables)',
+  'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:15:7: Variables must be declared using the keywords \'const\', \'final\', \'var\' or a type name (top-level declaration) (missing_const_final_var_or_type)',
+  'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:17:20: Private field could be final (top-level declaration) (prefer_final_fields)',
+  'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:17:20: The value of the field \'_buffer\' isn\'t used (top-level declaration) (unused_field)',
+];
+
 void main() {
   // These tests don't run on Windows because the sample analyzer doesn't
   // support Windows as a platform, since it is only run on Linux in the
@@ -17,55 +50,45 @@ void main() {
   test('analyze_snippet_code smoke test', () {
     final ProcessResult process = Process.runSync(
       '../../bin/cache/dart-sdk/bin/dart',
-      <String>['analyze_snippet_code.dart', '--no-include-dart-ui', 'test/analyze-snippet-code-test-input'],
+      <String>[
+        '--enable-asserts',
+        'analyze_snippet_code.dart',
+        '--no-include-dart-ui',
+        'test/analyze-snippet-code-test-input',
+      ],
     );
-    final List<String> stdoutLines = process.stdout.toString().split('\n');
+    expect(process.stdout, isEmpty);
     final List<String> stderrLines = process.stderr.toString().split('\n');
-    expect(process.exitCode, isNot(equals(0)));
+    expect(stderrLines.length, stderrLines.toSet().length, reason: 'found duplicates in $stderrLines');
-    expect(stderrLines, containsAll(<Object>[
+    expect(stderrLines, <String>[
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:138:25:     child: Text(title),',
+      ...expectedMainErrors,
-      matches(RegExp(r">>> error: The final variable 'title' can't be read because (it is|it's) potentially unassigned at this point \(read_potentially_unassigned_final\)")),
+      'Found 19 snippet code errors.',
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:30:9: new Opacity(',
+      'See the documentation at the top of dev/bots/analyze_snippet_code.dart for details.',
-      '>>> info: Unnecessary new keyword (unnecessary_new)',
+      '', // because we end with a newline, split gives us an extra blank line
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:62:9: new Opacity(',
+    ]);
-      '>>> info: Unnecessary new keyword (unnecessary_new)',
+    expect(process.exitCode, 1);
-      "dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:9: final String? bar = 'Hello';",
-      '>>> info: Prefer const over final for declarations (prefer_const_declarations)',
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:9: final int foo = null;',
-      '>>> info: Prefer const over final for declarations (prefer_const_declarations)',
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:25: final int foo = null;',
-      ">>> error: A value of type 'Null' can't be assigned to a variable of type 'int' (invalid_assignment)",
-      'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:120:24: const SizedBox(),',
-      '>>> error: Unexpected comma at end of snippet code. (missing_identifier)',
-      'Found 1 snippet code errors.',
-    ]));
-    expect(stdoutLines, containsAll(<String>[
-      'Found 13 snippet code blocks',
-      'Starting analysis of code snippets.',
-    ]));
   });
+
   test('Analyzes dart:ui code', () {
     final ProcessResult process = Process.runSync(
       '../../bin/cache/dart-sdk/bin/dart',
       <String>[
+        '--enable-asserts',
         'analyze_snippet_code.dart',
         '--dart-ui-location=test/analyze-snippet-code-test-dart-ui',
         'test/analyze-snippet-code-test-input',
       ],
     );
-    final List<String> stdoutLines = process.stdout.toString().split('\n');
+    expect(process.stdout, isEmpty);
     final List<String> stderrLines = process.stderr.toString().split('\n');
-    expect(process.exitCode, isNot(equals(0)));
+    expect(stderrLines.length, stderrLines.toSet().length, reason: 'found duplicates in $stderrLines');
-    expect(stderrLines, containsAll(<String>[
+    expect(stderrLines, <String>[
-      'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:19:11:   error;',
+      ...expectedUiErrors,
-      ">>> error: Variables must be declared using the keywords 'const', 'final', 'var' or a type name (missing_const_final_var_or_type)",
+      ...expectedMainErrors,
-      'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:23:11:   @keepToString',
+      'Found 23 snippet code errors.',
-      ">>> error: Undefined name 'keepToString' used as an annotation (undefined_annotation)",
+      'See the documentation at the top of dev/bots/analyze_snippet_code.dart for details.',
-    ]));
+      '', // because we end with a newline, split gives us an extra blank line
-    expect(stdoutLines, containsAll(<String>[
+    ]);
-      // There is one snippet code section in the test's dummy dart:ui code.
+    expect(process.exitCode, 1);
-      'Found 14 snippet code blocks',
-      'Starting analysis of code snippets.',
-    ]));
   });
 }

examples/api/lib/widgets/sliver/sliver_opacity.1.dart

@@ -0,0 +1,75 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for SliverOpacity
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const MyApp());
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  static const String _title = 'Flutter Code Sample';
+
+  @override
+  Widget build(BuildContext context) {
+    return const MaterialApp(
+      title: _title,
+      home: MyStatefulWidget(),
+    );
+  }
+}
+
+class MyStatefulWidget extends StatefulWidget {
+  const MyStatefulWidget({super.key});
+
+  @override
+  State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
+}
+
+class _MyStatefulWidgetState extends State<MyStatefulWidget> {
+  static const List<Widget> _listItems = <Widget>[
+    ListTile(title: Text('Now you see me,')),
+    ListTile(title: Text("Now you don't!")),
+  ];
+
+  bool _visible = true;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('SliverOpacity demo'),
+      ),
+      body: CustomScrollView(
+        slivers: <Widget>[
+          const SliverToBoxAdapter(
+            child: ListTile(title: Text('Press on the button to toggle the list visibilty.')),
+          ),
+          const SliverToBoxAdapter(
+            child: ListTile(title: Text('Before the list...')),
+          ),
+          SliverOpacity(
+            opacity: _visible ? 1.0 : 0.0,
+            sliver: SliverList(
+              delegate: SliverChildListDelegate(_listItems),
+            ),
+          ),
+          const SliverToBoxAdapter(
+            child: ListTile(title: Text('Before the list...')),
+          ),
+        ],
+      ),
+      floatingActionButton: FloatingActionButton(
+        child: const Icon(Icons.disabled_visible),
+        onPressed: () {
+          setState(() {
+            _visible = !_visible;
+          });
+        },
+      ),
+    );
+  }
+}

examples/api/test/widgets/sliver/sliver_opacity.1_test.dart

@@ -0,0 +1,23 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/widgets/sliver/sliver_opacity.1.dart'
+    as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('SliverOpacity example', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.MyApp(),
+    );
+
+    final Finder button = find.byType(FloatingActionButton);
+    final Finder opacity = find.byType(SliverOpacity);
+    expect((tester.widget(opacity) as SliverOpacity).opacity, 1.0);
+    await tester.tap(button);
+    await tester.pump();
+    expect((tester.widget(opacity) as SliverOpacity).opacity, 0.0);
+  });
+}

packages/flutter/lib/cupertino.dart

@@ -31,6 +31,7 @@ export 'src/cupertino/constants.dart';
 export 'src/cupertino/context_menu.dart';
 export 'src/cupertino/context_menu_action.dart';
 export 'src/cupertino/date_picker.dart';
+export 'src/cupertino/debug.dart';
 export 'src/cupertino/desktop_text_selection.dart';
 export 'src/cupertino/dialog.dart';
 export 'src/cupertino/form_row.dart';

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

@@ -173,7 +173,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   /// controller goes from 0.0 to 1.0:
   ///
   /// ```dart
-  /// Animation<Alignment> _alignment1 = _controller.drive(
+  /// Animation<Alignment> alignment1 = _controller.drive(
   ///   AlignmentTween(
   ///     begin: Alignment.topLeft,
   ///     end: Alignment.topRight,
@@ -208,7 +208,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   /// values that depend on other variables:
   ///
   /// ```dart
-  /// Animation<Alignment> _alignment3 = _controller
+  /// Animation<Alignment> alignment3 = _controller
   ///   .drive(CurveTween(curve: Curves.easeIn))
   ///   .drive(AlignmentTween(
   ///     begin: Alignment.topLeft,
@@ -226,7 +226,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
   /// of red.
   ///
   /// ```dart
-  /// Animation<Color> _offset1 = Animation<double>.fromValueListenable(_scrollPosition)
+  /// Animation<Color> color = Animation<double>.fromValueListenable(_scrollPosition)
   ///   .drive(Animatable<Color>.fromCallback((double value) {
   ///     return Color.fromRGBO(value.round() % 255, 0, 0, 1);
   ///   }));

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

@@ -6,6 +6,9 @@ import 'package:flutter/widgets.dart';
 
 import 'localizations.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Asserts that the given context has a [Localizations] ancestor that contains
 /// a [CupertinoLocalizations] delegate.
 ///

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

@@ -7,6 +7,9 @@ import 'package:flutter/widgets.dart';
 
 import 'debug.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Determines the order of the columns inside [CupertinoDatePicker] in
 /// time and date time mode.
 enum DatePickerDateTimeOrder {

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

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// Examples can assume:
+// bool _giveVerse = false;
+
 import 'dart:ui' show lerpDouble;
 
 import 'package:flutter/foundation.dart';

packages/flutter/lib/src/foundation/assertions.dart

@@ -20,6 +20,8 @@ export 'stack_frame.dart' show StackFrame;
 // late bool draconisAmulet;
 // late Diagnosticable draconis;
 // void methodThatMayThrow() { }
+// class Trace implements StackTrace { late StackTrace vmTrace; }
+// class Chain implements StackTrace { Trace toTrace() => Trace(); }
 
 /// Signature for [FlutterError.onError] handler.
 typedef FlutterExceptionHandler = void Function(FlutterErrorDetails details);
@@ -933,24 +935,27 @@ class FlutterError extends Error with DiagnosticableTreeMixin implements Asserti
 
   /// Called by the Flutter framework before attempting to parse a [StackTrace].
   ///
-  /// Some [StackTrace] implementations have a different toString format from
+  /// Some [StackTrace] implementations have a different [toString] format from
-  /// what the framework expects, like ones from package:stack_trace. To make
+  /// what the framework expects, like ones from `package:stack_trace`. To make
   /// sure we can still parse and filter mangled [StackTrace]s, the framework
   /// first calls this function to demangle them.
   ///
-  /// This should be set in any environment that could propagate a non-standard
+  /// This should be set in any environment that could propagate an unusual
   /// stack trace to the framework. Otherwise, the default behavior is to assume
-  /// all stack traces are in a standard format.
+  /// all stack traces are in a format usually generated by Dart.
   ///
-  /// The following example demangles package:stack_trace traces by converting
+  /// The following example demangles `package:stack_trace` traces by converting
-  /// them into vm traces, which the framework is able to parse:
+  /// them into VM traces, which the framework is able to parse:
   ///
   /// ```dart
-  /// FlutterError.demangleStackTrace = (StackTrace stackTrace) {
+  /// FlutterError.demangleStackTrace = (StackTrace stack) {
-  ///   if (stack is stack_trace.Trace)
+  ///   // Trace and Chain are classes in package:stack_trace
+  ///   if (stack is Trace) {
   ///     return stack.vmTrace;
-  ///   if (stack is stack_trace.Chain)
+  ///   }
+  ///   if (stack is Chain) {
   ///     return stack.toTrace().vmTrace;
+  ///   }
   ///   return stack;
   /// };
   /// ```

packages/flutter/lib/src/foundation/basic_types.dart

@@ -115,9 +115,10 @@ class CachingIterable<E> extends IterableBase<E> {
   ///
   /// ```dart
   /// Iterable<int> range(int start, int end) sync* {
-  ///   for (int index = start; index <= end; index += 1)
+  ///   for (int index = start; index <= end; index += 1) {
   ///     yield index;
-  ///  }
+  ///   }
+  /// }
   ///
   /// Iterable<int> i = CachingIterable<int>(range(1, 5).iterator);
   /// print(i.length); // walks the list

packages/flutter/lib/src/foundation/binding.dart

@@ -119,6 +119,7 @@ typedef ServiceExtensionCallback = Future<Map<String, dynamic>> Function(Map<Str
 /// class.
 ///
 /// ```dart
+/// // continuing from previous example...
 /// class FooLibraryBinding extends BindingBase with BarBinding, FooBinding {
 ///   static FooBinding ensureInitialized() {
 ///     if (FooBinding._instance == null) {

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -16,6 +16,32 @@ import 'object.dart';
 // late int rows, columns;
 // late String _name;
 // late bool inherit;
+// abstract class ExampleSuperclass with Diagnosticable { }
+// late String message;
+// late double stepWidth;
+// late double scale;
+// late double hitTestExtent;
+// late double paintExtent;
+// late double maxWidth;
+// late double progress;
+// late int maxLines;
+// late Duration duration;
+// late int depth;
+// late bool primary;
+// late bool isCurrent;
+// late bool keepAlive;
+// late bool obscureText;
+// late TextAlign textAlign;
+// late ImageRepeat repeat;
+// late Widget widget;
+// late List<BoxShadow> boxShadow;
+// late Size size;
+// late bool hasSize;
+// late Matrix4 transform;
+// late Color color;
+// late Map<Listenable, VoidCallback>? handles;
+// late DiagnosticsTreeStyle style;
+// late IconData icon;
 
 /// The various priority levels used to filter which diagnostics are shown and
 /// omitted.
@@ -383,30 +409,29 @@ class TextTreeConfiguration {
 /// Default text tree configuration.
 ///
 /// Example:
-/// ```
+///
-/// <root_name>: <root_description>
+///     <root_name>: <root_description>
-///  │ <property1>
+///      │ <property1>
-///  │ <property2>
+///      │ <property2>
-///  │ ...
+///      │ ...
-///  │ <propertyN>
+///      │ <propertyN>
-///  ├─<child_name>: <child_description>
+///      ├─<child_name>: <child_description>
-///  │ │ <property1>
+///      │ │ <property1>
-///  │ │ <property2>
+///      │ │ <property2>
-///  │ │ ...
+///      │ │ ...
-///  │ │ <propertyN>
+///      │ │ <propertyN>
-///  │ │
+///      │ │
-///  │ └─<child_name>: <child_description>
+///      │ └─<child_name>: <child_description>
-///  │     <property1>
+///      │     <property1>
-///  │     <property2>
+///      │     <property2>
-///  │     ...
+///      │     ...
-///  │     <propertyN>
+///      │     <propertyN>
-///  │
+///      │
-///  └─<child_name>: <child_description>'
+///      └─<child_name>: <child_description>'
-///    <property1>
+///        <property1>
-///    <property2>
+///        <property2>
-///    ...
+///        ...
-///    <propertyN>
+///        <propertyN>
-/// ```
 ///
 /// See also:
 ///
@@ -425,42 +450,41 @@ final TextTreeConfiguration sparseTextConfiguration = TextTreeConfiguration(
 /// parent to children are dashed.
 ///
 /// Example:
-/// ```
+///
-/// <root_name>: <root_description>
+///     <root_name>: <root_description>
-///  │ <property1>
+///      │ <property1>
-///  │ <property2>
+///      │ <property2>
-///  │ ...
+///      │ ...
-///  │ <propertyN>
+///      │ <propertyN>
-///  ├─<normal_child_name>: <child_description>
+///      ├─<normal_child_name>: <child_description>
-///  ╎ │ <property1>
+///      ╎ │ <property1>
-///  ╎ │ <property2>
+///      ╎ │ <property2>
-///  ╎ │ ...
+///      ╎ │ ...
-///  ╎ │ <propertyN>
+///      ╎ │ <propertyN>
-///  ╎ │
+///      ╎ │
-///  ╎ └─<child_name>: <child_description>
+///      ╎ └─<child_name>: <child_description>
-///  ╎     <property1>
+///      ╎     <property1>
-///  ╎     <property2>
+///      ╎     <property2>
-///  ╎     ...
+///      ╎     ...
-///  ╎     <propertyN>
+///      ╎     <propertyN>
-///  ╎
+///      ╎
-///  ╎╌<dashed_child_name>: <child_description>
+///      ╎╌<dashed_child_name>: <child_description>
-///  ╎ │ <property1>
+///      ╎ │ <property1>
-///  ╎ │ <property2>
+///      ╎ │ <property2>
-///  ╎ │ ...
+///      ╎ │ ...
-///  ╎ │ <propertyN>
+///      ╎ │ <propertyN>
-///  ╎ │
+///      ╎ │
-///  ╎ └─<child_name>: <child_description>
+///      ╎ └─<child_name>: <child_description>
-///  ╎     <property1>
+///      ╎     <property1>
-///  ╎     <property2>
+///      ╎     <property2>
-///  ╎     ...
+///      ╎     ...
-///  ╎     <propertyN>
+///      ╎     <propertyN>
-///  ╎
+///      ╎
-///  └╌<dashed_child_name>: <child_description>'
+///      └╌<dashed_child_name>: <child_description>'
-///    <property1>
+///        <property1>
-///    <property2>
+///        <property2>
-///    ...
+///        ...
-///    <propertyN>
+///        <propertyN>
-/// ```
 ///
 /// See also:
 ///
@@ -480,11 +504,10 @@ final TextTreeConfiguration dashedTextConfiguration = TextTreeConfiguration(
 /// Dense text tree configuration that minimizes horizontal whitespace.
 ///
 /// Example:
-/// ```
+///
-/// <root_name>: <root_description>(<property1>; <property2> <propertyN>)
+///     <root_name>: <root_description>(<property1>; <property2> <propertyN>)
-/// ├<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
+///     ├<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
-/// └<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
+///     └<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
-/// ```
 ///
 /// See also:
 ///
@@ -511,19 +534,18 @@ final TextTreeConfiguration denseTextConfiguration = TextTreeConfiguration(
 /// contents of a node.
 ///
 /// Example:
-/// ```
+///
-///  <parent_node>
+///     <parent_node>
-///  ╞═╦══ <name> ═══
+///     ╞═╦══ <name> ═══
-///  │ ║  <description>:
+///     │ ║  <description>:
-///  │ ║    <body>
+///     │ ║    <body>
-///  │ ║    ...
+///     │ ║    ...
-///  │ ╚═══════════
+///     │ ╚═══════════
-///  ╘═╦══ <name> ═══
+///     ╘═╦══ <name> ═══
-///    ║  <description>:
+///       ║  <description>:
-///    ║    <body>
+///       ║    <body>
-///    ║    ...
+///       ║    ...
-///    ╚═══════════
+///       ╚═══════════
-/// ```
 ///
 /// See also:
 ///
@@ -563,37 +585,36 @@ final TextTreeConfiguration transitionTextConfiguration = TextTreeConfiguration(
 /// Used to draw a decorative box around detailed descriptions of an exception.
 ///
 /// Example:
-/// ```
+///
-/// ══╡ <name>: <description> ╞═════════════════════════════════════
+///     ══╡ <name>: <description> ╞═════════════════════════════════════
-/// <body>
+///     <body>
-/// ...
+///     ...
-/// ├─<normal_child_name>: <child_description>
+///     ├─<normal_child_name>: <child_description>
-/// ╎ │ <property1>
+///     ╎ │ <property1>
-/// ╎ │ <property2>
+///     ╎ │ <property2>
-/// ╎ │ ...
+///     ╎ │ ...
-/// ╎ │ <propertyN>
+///     ╎ │ <propertyN>
-/// ╎ │
+///     ╎ │
-/// ╎ └─<child_name>: <child_description>
+///     ╎ └─<child_name>: <child_description>
-/// ╎     <property1>
+///     ╎     <property1>
-/// ╎     <property2>
+///     ╎     <property2>
-/// ╎     ...
+///     ╎     ...
-/// ╎     <propertyN>
+///     ╎     <propertyN>
-/// ╎
+///     ╎
-/// ╎╌<dashed_child_name>: <child_description>
+///     ╎╌<dashed_child_name>: <child_description>
-/// ╎ │ <property1>
+///     ╎ │ <property1>
-/// ╎ │ <property2>
+///     ╎ │ <property2>
-/// ╎ │ ...
+///     ╎ │ ...
-/// ╎ │ <propertyN>
+///     ╎ │ <propertyN>
-/// ╎ │
+///     ╎ │
-/// ╎ └─<child_name>: <child_description>
+///     ╎ └─<child_name>: <child_description>
-/// ╎     <property1>
+///     ╎     <property1>
-/// ╎     <property2>
+///     ╎     <property2>
-/// ╎     ...
+///     ╎     ...
-/// ╎     <propertyN>
+///     ╎     <propertyN>
-/// ╎
+///     ╎
-/// └╌<dashed_child_name>: <child_description>'
+///     └╌<dashed_child_name>: <child_description>'
-/// ════════════════════════════════════════════════════════════════
+///     ════════════════════════════════════════════════════════════════
-/// ```
 ///
 /// See also:
 ///
@@ -626,15 +647,14 @@ final TextTreeConfiguration errorTextConfiguration = TextTreeConfiguration(
 /// draws line art would be visually distracting for those cases.
 ///
 /// Example:
-/// ```
+///
-/// <parent_node>
+///     <parent_node>
-///   <name>: <description>:
+///       <name>: <description>:
-///     <properties>
+///         <properties>
-///     <children>
+///         <children>
-///   <name>: <description>:
+///       <name>: <description>:
-///     <properties>
+///         <properties>
-///     <children>
+///         <children>
-/// ```
 ///
 /// See also:
 ///
@@ -660,15 +680,14 @@ final TextTreeConfiguration whitespaceTextConfiguration = TextTreeConfiguration(
 /// children as in the case of a [DiagnosticsStackTrace].
 ///
 /// Example:
-/// ```
+///
-/// <parent_node>
+///     <parent_node>
-/// <name>: <description>:
+///     <name>: <description>:
-/// <properties>
+///     <properties>
-/// <children>
+///     <children>
-/// <name>: <description>:
+///     <name>: <description>:
-/// <properties>
+///     <properties>
-/// <children>
+///     <children>
-/// ```
 ///
 /// See also:
 ///
@@ -716,10 +735,9 @@ final TextTreeConfiguration singleLineTextConfiguration = TextTreeConfiguration(
 /// line omitting the children.
 ///
 /// Example:
-/// ```
+///
-/// <name>:
+///     <name>:
-///   <description>(<property1>, <property2>, ..., <propertyN>)
+///       <description>(<property1>, <property2>, ..., <propertyN>)
-/// ```
 ///
 /// See also:
 ///
@@ -3162,7 +3180,7 @@ mixin Diagnosticable {
   ///    Shows using `showSeparator` to get output `child(3, 4) is null` which
   ///    is more polished than `child(3, 4): is null`.
   ///    ```dart
-  ///    DiagnosticsProperty<IconData>('icon', icon, ifNull: '<empty>', showName: false)).toString()
+  ///    DiagnosticsProperty<IconData>('icon', icon, ifNull: '<empty>', showName: false).toString()
   ///    ```
   ///    Shows using `showName` to omit the property name as in this context the
   ///    property name does not add useful information.
@@ -3238,7 +3256,7 @@ mixin Diagnosticable {
   ///     properties.add(DoubleProperty('hitTestExtent', hitTestExtent, defaultValue: paintExtent));
   ///
   ///     // maxWidth of double.infinity indicates the width is unconstrained and
-  ///     // so maxWidth has no impact.,
+  ///     // so maxWidth has no impact.
   ///     properties.add(DoubleProperty('maxWidth', maxWidth, defaultValue: double.infinity));
   ///
   ///     // Progress is a value between 0 and 1 or null. Showing it as a

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

@@ -184,9 +184,10 @@ int nthStylusButton(int number) => (kPrimaryStylusButton << (number - 1)) & kMax
 /// Example:
 ///
 /// ```dart
-///   assert(rightmostButton(0x1) == 0x1);
+/// assert(smallestButton(0x01) == 0x01);
-///   assert(rightmostButton(0x11) == 0x1);
+/// assert(smallestButton(0x11) == 0x01);
-///   assert(rightmostButton(0) == 0);
+/// assert(smallestButton(0x10) == 0x10);
+/// assert(smallestButton(0) == 0);
 /// ```
 ///
 /// See also:

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

@@ -204,7 +204,7 @@ class ForcePressGestureRecognizer extends OneSequenceGestureRecognizer {
   /// value:
   ///
   /// ```dart
-  /// static double interpolateWithEasing(double min, double max, double t) {
+  /// double interpolateWithEasing(double min, double max, double t) {
   ///    final double lerp = (t - min) / (max - min);
   ///    return Curves.easeIn.transform(lerp);
   /// }

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

@@ -30,6 +30,9 @@ import 'text_button.dart';
 import 'text_theme.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// BuildContext context;
+
 /// A [ListTile] that shows an about box.
 ///
 /// This widget is often added to an app's [Drawer]. When tapped it shows
@@ -1062,14 +1065,14 @@ class _MasterDetailFlow extends StatefulWidget {
   @override
   _MasterDetailFlowState createState() => _MasterDetailFlowState();
 
-  /// The master detail flow proxy from the closest instance of this class that encloses the given
+  // The master detail flow proxy from the closest instance of this class that encloses the given
-  /// context.
+  // context.
-  ///
+  //
-  /// Typical usage is as follows:
+  // Typical usage is as follows:
-  ///
+  //
-  /// ```dart
+  // ```dart
-  /// _MasterDetailFlow.of(context).openDetailPage(arguments);
+  // _MasterDetailFlow.of(context).openDetailPage(arguments);
-  /// ```
+  // ```
   static _MasterDetailFlowProxy? of(BuildContext context) {
     _PageOpener? pageOpener = context.findAncestorStateOfType<_MasterDetailScaffoldState>();
     pageOpener ??= context.findAncestorStateOfType<_MasterDetailFlowState>();

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

@@ -19,6 +19,10 @@ import 'scrollbar.dart';
 import 'theme.dart';
 import 'tooltip.dart';
 
+// Examples can assume:
+// typedef GlobalWidgetsLocalizations = DefaultWidgetsLocalizations;
+// typedef GlobalMaterialLocalizations = DefaultMaterialLocalizations;
+
 /// [MaterialApp] uses this [TextStyle] as its [DefaultTextStyle] to encourage
 /// developers to be intentional about their [DefaultTextStyle].
 ///
@@ -171,7 +175,7 @@ enum ThemeMode {
 /// a [Material] widget that defines its default text style.
 ///
 /// ```dart
-/// MaterialApp(
+/// const MaterialApp(
 ///   title: 'Material App',
 ///   home: Scaffold(
 ///     body: Center(
@@ -513,16 +517,19 @@ class MaterialApp extends StatefulWidget {
   /// and list the [supportedLocales] that the application can handle.
   ///
   /// ```dart
-  /// import 'package:flutter_localizations/flutter_localizations.dart';
+  /// // The GlobalMaterialLocalizations and GlobalWidgetsLocalizations
-  /// MaterialApp(
+  /// // classes require the following import:
-  ///   localizationsDelegates: [
+  /// // import 'package:flutter_localizations/flutter_localizations.dart';
-  ///     // ... app-specific localization delegate[s] here
+  ///
+  /// const MaterialApp(
+  ///   localizationsDelegates: <LocalizationsDelegate<Object>>[
+  ///     // ... app-specific localization delegate(s) here
   ///     GlobalMaterialLocalizations.delegate,
   ///     GlobalWidgetsLocalizations.delegate,
   ///   ],
-  ///   supportedLocales: [
+  ///   supportedLocales: <Locale>[
-  ///     const Locale('en', 'US'), // English
+  ///     Locale('en', 'US'), // English
-  ///     const Locale('he', 'IL'), // Hebrew
+  ///     Locale('he', 'IL'), // Hebrew
   ///     // ... other locales the app supports
   ///   ],
   ///   // ...
@@ -542,33 +549,39 @@ class MaterialApp extends StatefulWidget {
   /// [LocalizationsDelegate<MaterialLocalizations>] whose load methods return
   /// custom versions of [WidgetsLocalizations] or [MaterialLocalizations].
   ///
-  /// For example: to add support to [MaterialLocalizations] for a
+  /// For example: to add support to [MaterialLocalizations] for a locale it
-  /// locale it doesn't already support, say `const Locale('foo', 'BR')`,
+  /// doesn't already support, say `const Locale('foo', 'BR')`, one first
-  /// one could just extend [DefaultMaterialLocalizations]:
+  /// creates a subclass of [MaterialLocalizations] that provides the
+  /// translations:
   ///
   /// ```dart
-  /// class FooLocalizations extends DefaultMaterialLocalizations {
+  /// class FooLocalizations extends MaterialLocalizations {
-  ///   FooLocalizations(Locale locale) : super(locale);
+  ///   FooLocalizations();
   ///   @override
-  ///   String get okButtonLabel {
+  ///   String get okButtonLabel => 'foo';
-  ///     if (locale == const Locale('foo', 'BR'))
+  ///   // ...
-  ///       return 'foo';
+  ///   // lots of other getters and methods to override!
-  ///     return super.okButtonLabel;
-  ///   }
   /// }
-  ///
   /// ```
   ///
-  /// A `FooLocalizationsDelegate` is essentially just a method that constructs
+  /// One must then create a [LocalizationsDelegate] subclass that can provide
-  /// a `FooLocalizations` object. We return a [SynchronousFuture] here because
+  /// an instance of the [MaterialLocalizations] subclass. In this case, this is
-  /// no asynchronous work takes place upon "loading" the localizations object.
+  /// essentially just a method that constructs a `FooLocalizations` object. A
+  /// [SynchronousFuture] is used here because no asynchronous work takes place
+  /// upon "loading" the localizations object.
   ///
   /// ```dart
+  /// // continuing from previous example...
   /// class FooLocalizationsDelegate extends LocalizationsDelegate<MaterialLocalizations> {
   ///   const FooLocalizationsDelegate();
   ///   @override
+  ///   bool isSupported(Locale locale) {
+  ///     return locale == const Locale('foo', 'BR');
+  ///   }
+  ///   @override
   ///   Future<FooLocalizations> load(Locale locale) {
-  ///     return SynchronousFuture(FooLocalizations(locale));
+  ///     assert(locale == const Locale('foo', 'BR'));
+  ///     return SynchronousFuture<FooLocalizations>(FooLocalizations());
   ///   }
   ///   @override
   ///   bool shouldReload(FooLocalizationsDelegate old) => false;
@@ -582,9 +595,10 @@ class MaterialApp extends StatefulWidget {
   /// [localizationsDelegates] list.
   ///
   /// ```dart
-  /// MaterialApp(
+  /// // continuing from previous example...
-  ///   localizationsDelegates: [
+  /// const MaterialApp(
-  ///     const FooLocalizationsDelegate(),
+  ///   localizationsDelegates: <LocalizationsDelegate<Object>>[
+  ///     FooLocalizationsDelegate(),
   ///   ],
   ///   // ...
   /// )

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

@@ -25,6 +25,10 @@ import 'tabs.dart';
 import 'text_theme.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late String _logoAsset;
+// double _myToolbarHeight = 250.0;
+
 const double _kLeadingWidth = kToolbarHeight; // So the leading button is square.
 const double _kMaxTitleTextScaleFactor = 1.34; // TODO(perc): Add link to Material spec when available, https://github.com/flutter/flutter/issues/58769.
 
@@ -319,10 +323,10 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   ///   home: Scaffold(
   ///     appBar: AppBar(
   ///       title: SizedBox(
-  ///         height: toolbarHeight,
+  ///         height: _myToolbarHeight,
-  ///         child: Image.asset(logoAsset),
+  ///         child: Image.asset(_logoAsset),
   ///       ),
-  ///       toolbarHeight: toolbarHeight,
+  ///       toolbarHeight: _myToolbarHeight,
   ///     ),
   ///   ),
   /// )

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

@@ -10,6 +10,9 @@ import 'material.dart';
 import 'scaffold.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 const Duration _materialBannerTransitionDuration = Duration(milliseconds: 250);
 const Curve _materialBannerHeightCurve = Curves.fastOutSlowIn;
 
@@ -24,9 +27,14 @@ const Curve _materialBannerHeightCurve = Curves.fastOutSlowIn;
 ///
 /// ```dart
 /// ScaffoldMessenger.of(context).showMaterialBanner(
-///   MaterialBanner( ... )
+///   const MaterialBanner(
+///     content: Text('Message...'),
+///     actions: <Widget>[
+///       // ...
+///     ],
+///   )
 /// ).closed.then((MaterialBannerClosedReason reason) {
-///    ...
+///    // ...
 /// });
 /// ```
 enum MaterialBannerClosedReason {

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

@@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of [MaterialBanner] widgets.
 ///
 /// Descendant widgets obtain the current [MaterialBannerThemeData] object using

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

@@ -11,6 +11,9 @@ import 'bottom_navigation_bar.dart';
 import 'material_state.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [BottomNavigationBar]
 /// widgets.
 ///

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 import 'button_theme.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of [ButtonBar] widgets.
 ///
 /// Used by [ButtonBarTheme] to control the visual properties of [ButtonBar]

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

@@ -12,6 +12,10 @@ import 'ink_well.dart';
 import 'material_state.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late BuildContext context;
+// typedef MyAppHome = Placeholder;
+
 /// The visual properties that most buttons have in common.
 ///
 /// Buttons and their themes have a ButtonStyle property which defines the visual
@@ -37,13 +41,18 @@ import 'theme_data.dart';
 ///   style: ButtonStyle(
 ///     backgroundColor: MaterialStateProperty.resolveWith<Color?>(
 ///       (Set<MaterialState> states) {
-///         if (states.contains(MaterialState.pressed))
+///         if (states.contains(MaterialState.pressed)) {
 ///           return Theme.of(context).colorScheme.primary.withOpacity(0.5);
+///         }
 ///         return null; // Use the component's default.
 ///       },
 ///     ),
 ///   ),
-/// )
+///   child: const Text('Fly me to the moon'),
+///   onPressed: () {
+///     // ...
+///   },
+/// ),
 /// ```
 ///
 /// In this case the background color for all other button states would fallback
@@ -52,10 +61,14 @@ import 'theme_data.dart';
 ///
 /// ```dart
 /// ElevatedButton(
-///   style: ButtonStyle(
+///   style: const ButtonStyle(
 ///     backgroundColor: MaterialStatePropertyAll<Color>(Colors.green),
 ///   ),
-/// )
+///   child: const Text('Let me play among the stars'),
+///   onPressed: () {
+///     // ...
+///   },
+/// ),
 /// ```
 ///
 /// Configuring a ButtonStyle directly makes it possible to very
@@ -76,11 +89,16 @@ import 'theme_data.dart';
 /// ```dart
 /// TextButton(
 ///   style: TextButton.styleFrom(foregroundColor: Colors.green),
-/// )
+///   child: const Text('Let me see what spring is like'),
+///   onPressed: () {
+///     // ...
+///   },
+/// ),
 /// ```
 ///
 /// To configure all of the application's text buttons in the same
 /// way, specify the overall theme's `textButtonTheme`:
+///
 /// ```dart
 /// MaterialApp(
 ///   theme: ThemeData(
@@ -88,8 +106,8 @@ import 'theme_data.dart';
 ///       style: TextButton.styleFrom(foregroundColor: Colors.green),
 ///     ),
 ///   ),
-///   home: MyAppHome(),
+///   home: const MyAppHome(),
-/// )
+/// ),
 /// ```
 ///
 /// ## Material 3 button types
@@ -285,7 +303,7 @@ class ButtonStyle with Diagnosticable {
   ///     splashFactory: NoSplash.splashFactory,
   ///   ),
   ///   onPressed: () { },
-  ///   child: Text('No Splash'),
+  ///   child: const Text('No Splash'),
   /// )
   /// ```
   final InteractiveInkFeatureFactory? splashFactory;

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

@@ -13,6 +13,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart' show MaterialTapTargetSize;
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Used with [ButtonTheme] and [ButtonThemeData] to define a button's base
 /// colors, and the defaults for the button's minimum size, internal padding,
 /// and shape.
@@ -232,14 +235,7 @@ class ButtonThemeData with Diagnosticable {
   final ButtonBarLayoutBehavior layoutBehavior;
 
   /// Simply a convenience that returns [minWidth] and [height] as a
-  /// [BoxConstraints] object:
+  /// [BoxConstraints] object.
-  ///
-  /// ```dart
-  /// return BoxConstraints(
-  ///   minWidth: minWidth,
-  ///   minHeight: height,
-  /// );
-  /// ```
   BoxConstraints get constraints {
     return BoxConstraints(
       minWidth: minWidth,

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

@@ -906,19 +906,18 @@ class _DayPickerState extends State<_DayPicker> {
   ///
   /// Examples:
   ///
-  /// ```
+  ///     ┌ Sunday is the first day of week in the US (en_US)
-  /// ┌ Sunday is the first day of week in the US (en_US)
+  ///     |
-  /// |
+  ///     S M T W T F S  ← the returned list contains these widgets
-  /// S M T W T F S  <-- the returned list contains these widgets
+  ///     _ _ _ _ _ 1 2
-  /// _ _ _ _ _ 1 2
+  ///     3 4 5 6 7 8 9
-  /// 3 4 5 6 7 8 9
+  ///
+  ///     ┌ But it's Monday in the UK (en_GB)
+  ///     |
+  ///     M T W T F S S  ← the returned list contains these widgets
+  ///     _ _ _ _ 1 2 3
+  ///     4 5 6 7 8 9 10
   ///
-  /// ┌ But it's Monday in the UK (en_GB)
-  /// |
-  /// M T W T F S S  <-- the returned list contains these widgets
-  /// _ _ _ _ 1 2 3
-  /// 4 5 6 7 8 9 10
-  /// ```
   List<Widget> _dayHeaders(TextStyle? headerStyle, MaterialLocalizations localizations) {
     final List<Widget> result = <Widget>[];
     for (int i = localizations.firstDayOfWeekIndex; true; i = (i + 1) % 7) {

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

@@ -12,6 +12,10 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'toggleable.dart';
 
+// Examples can assume:
+// bool _throwShotAway = false;
+// late StateSetter setState;
+
 /// A Material Design checkbox.
 ///
 /// The checkbox itself does not maintain any state. Instead, when the state of

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

@@ -13,7 +13,7 @@ import 'theme.dart';
 import 'theme_data.dart';
 
 // Examples can assume:
-// bool? _throwShotAway = false;
+// late bool? _throwShotAway;
 // void setState(VoidCallback fn) { }
 
 /// A [ListTile] with a [Checkbox]. In other words, a checkbox with a label.

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

@@ -12,6 +12,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [Checkbox] widgets.
 ///
 /// Descendant widgets obtain the current [CheckboxThemeData] object using

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

@@ -21,6 +21,11 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'tooltip.dart';
 
+// Examples can assume:
+// late BuildContext context;
+// late List<DataColumn> _columns;
+// late List<DataRow> _rows;
+
 /// Signature for [DataColumn.onSort] callback.
 typedef DataColumnSortCallback = void Function(int columnIndex, bool ascending);
 
@@ -183,10 +188,14 @@ class DataRow {
   /// ```dart
   /// DataRow(
   ///   color: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
-  ///     if (states.contains(MaterialState.selected))
+  ///     if (states.contains(MaterialState.selected)) {
   ///       return Theme.of(context).colorScheme.primary.withOpacity(0.08);
+  ///     }
   ///     return null;  // Use the default value.
   ///   }),
+  ///   cells: const <DataCell>[
+  ///     // ...
+  ///   ],
   /// )
   /// ```
   ///
@@ -474,10 +483,13 @@ class DataTable extends StatelessWidget {
   /// ```dart
   /// DataTable(
   ///   dataRowColor: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
-  ///     if (states.contains(MaterialState.selected))
+  ///     if (states.contains(MaterialState.selected)) {
   ///       return Theme.of(context).colorScheme.primary.withOpacity(0.08);
+  ///     }
   ///     return null;  // Use the default value.
   ///   }),
+  ///   columns: _columns,
+  ///   rows: _rows,
   /// )
   /// ```
   ///
@@ -521,9 +533,12 @@ class DataTable extends StatelessWidget {
   /// {@template flutter.material.DataTable.headingRowColor}
   /// ```dart
   /// DataTable(
+  ///   columns: _columns,
+  ///   rows: _rows,
   ///   headingRowColor: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
-  ///     if (states.contains(MaterialState.hovered))
+  ///     if (states.contains(MaterialState.hovered)) {
   ///       return Theme.of(context).colorScheme.primary.withOpacity(0.08);
+  ///     }
   ///     return null;  // Use the default value.
   ///   }),
   /// )

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 import 'material_state.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [DataTable]
 /// widgets.
 ///

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

@@ -47,10 +47,11 @@ class DateUtils {
   /// Determines the number of months between two [DateTime] objects.
   ///
   /// For example:
-  /// ```
+  ///
-  /// DateTime date1 = DateTime(year: 2019, month: 6, day: 15);
+  /// ```dart
-  /// DateTime date2 = DateTime(year: 2020, month: 1, day: 15);
+  /// DateTime date1 = DateTime(2019, 6, 15);
-  /// int delta = monthDelta(date1, date2);
+  /// DateTime date2 = DateTime(2020, 1, 15);
+  /// int delta = DateUtils.monthDelta(date1, date2);
   /// ```
   ///
   /// The value for `delta` would be `7`.
@@ -62,8 +63,9 @@ class DateUtils {
   /// of months and the day set to 1 and time set to midnight.
   ///
   /// For example:
-  /// ```
+  ///
-  /// DateTime date = DateTime(year: 2019, month: 1, day: 15);
+  /// ```dart
+  /// DateTime date = DateTime(2019, 1, 15);
   /// DateTime futureDate = DateUtils.addMonthsToMonthDate(date, 3);
   /// ```
   ///
@@ -85,10 +87,8 @@ class DateUtils {
   /// For example, September 1, 2017 falls on a Friday, which in the calendar
   /// localized for United States English appears as:
   ///
-  /// ```
+  ///     S M T W T F S
-  /// S M T W T F S
+  ///     _ _ _ _ _ 1 2
-  /// _ _ _ _ _ 1 2
-  /// ```
   ///
   /// The offset for the first day of the months is the number of leading blanks
   /// in the calendar, i.e. 5.
@@ -96,10 +96,8 @@ class DateUtils {
   /// The same date localized for the Russian calendar has a different offset,
   /// because the first day of week is Monday rather than Sunday:
   ///
-  /// ```
+  ///     M T W T F S S
-  /// M T W T F S S
+  ///     _ _ _ _ 1 2 3
-  /// _ _ _ _ 1 2 3
-  /// ```
   ///
   /// So the offset is 4, rather than 5.
   ///

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

@@ -1954,19 +1954,18 @@ class _DayHeaders extends StatelessWidget {
   ///
   /// Examples:
   ///
-  /// ```
+  ///     ┌ Sunday is the first day of week in the US (en_US)
-  /// ┌ Sunday is the first day of week in the US (en_US)
+  ///     |
-  /// |
+  ///     S M T W T F S  ← the returned list contains these widgets
-  /// S M T W T F S  <-- the returned list contains these widgets
+  ///     _ _ _ _ _ 1 2
-  /// _ _ _ _ _ 1 2
+  ///     3 4 5 6 7 8 9
-  /// 3 4 5 6 7 8 9
+  ///
+  ///     ┌ But it's Monday in the UK (en_GB)
+  ///     |
+  ///     M T W T F S S  ← the returned list contains these widgets
+  ///     _ _ _ _ 1 2 3
+  ///     4 5 6 7 8 9 10
   ///
-  /// ┌ But it's Monday in the UK (en_GB)
-  /// |
-  /// M T W T F S S  <-- the returned list contains these widgets
-  /// _ _ _ _ 1 2 3
-  /// 4 5 6 7 8 9 10
-  /// ```
   List<Widget> _getDayHeaders(TextStyle headerStyle, MaterialLocalizations localizations) {
     final List<Widget> result = <Widget>[];
     for (int i = localizations.firstDayOfWeekIndex; true; i = (i + 1) % 7) {

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

@@ -8,6 +8,9 @@ import 'material.dart';
 import 'material_localizations.dart';
 import 'scaffold.dart' show Scaffold, ScaffoldMessenger;
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Asserts that the given context has a [Material] ancestor.
 ///
 /// Used by many Material Design widgets to make sure that they are

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

@@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of [Divider], [VerticalDivider], dividers
 /// between [ListTile]s, and dividers between rows in [DataTable]s.
 ///

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

@@ -14,6 +14,9 @@ import 'material.dart';
 import 'material_localizations.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// The possible alignments of a [Drawer].
 enum DrawerAlignment {
   /// Denotes that the [Drawer] is at the start side of the [Scaffold].
@@ -117,8 +120,8 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
 ///
 /// ```dart
 /// ListTile(
-///   leading: Icon(Icons.change_history),
+///   leading: const Icon(Icons.change_history),
-///   title: Text('Change history'),
+///   title: const Text('Change history'),
 ///   onTap: () {
 ///     // change app state...
 ///     Navigator.pop(context); // close the drawer

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [Drawer] widgets.
 ///
 /// Descendant widgets obtain the current [DrawerThemeData] object

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

@@ -130,7 +130,11 @@ class ElevatedButton extends ButtonStyleButton {
   /// ```dart
   /// ElevatedButton(
   ///   style: ElevatedButton.styleFrom(foregroundColor: Colors.green),
-  /// )
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
+  ///   child: const Text('Jump'),
+  /// ),
   /// ```
   ///
   /// And to change the fill color:
@@ -138,7 +142,11 @@ class ElevatedButton extends ButtonStyleButton {
   /// ```dart
   /// ElevatedButton(
   ///   style: ElevatedButton.styleFrom(backgroundColor: Colors.green),
-  /// )
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
+  ///   child: const Text('Meow'),
+  /// ),
   /// ```
   ///
   static ButtonStyle styleFrom({

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

@@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
 import 'button_style.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// A [ButtonStyle] that overrides the default appearance of
 /// [ElevatedButton]s when it's used with [ElevatedButtonTheme] or with the
 /// overall [Theme]'s [ThemeData.elevatedButtonTheme].

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

@@ -2,12 +2,14 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-
 import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Used with [ExpansionTileTheme] to define default property values for
 /// descendant [ExpansionTile] widgets.
 ///

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

@@ -23,6 +23,9 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'tooltip.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 // Minimum logical pixel size of the IconButton.
 // See: <https://material.io/design/usability/accessibility.html#layout-typography>.
 const double _kMinButtonSize = kMinInteractiveDimension;
@@ -61,16 +64,27 @@ const double _kMinButtonSize = kMinInteractiveDimension;
 ///
 /// When creating an icon button with an [Icon], do not override the
 /// icon's size with its [Icon.size] parameter, use the icon button's
-/// [iconSize] parameter instead.  For example do this:
+/// [iconSize] parameter instead. For example do this:
 ///
 /// ```dart
-/// IconButton(iconSize: 72, icon: Icon(Icons.favorite), ...)
+/// IconButton(
+///   iconSize: 72,
+///   icon: const Icon(Icons.favorite),
+///   onPressed: () {
+///     // ...
+///   },
+/// ),
 /// ```
 ///
 /// Avoid doing this:
 ///
 /// ```dart
-/// IconButton(icon: Icon(Icons.favorite, size: 72), ...)
+/// IconButton(
+///   icon: const Icon(Icons.favorite, size: 72),
+///   onPressed: () {
+///     // ...
+///   },
+/// ),
 /// ```
 ///
 /// If you do, the button's size will be based on the default icon
@@ -257,6 +271,10 @@ class IconButton extends StatelessWidget {
   /// ```dart
   /// IconButton(
   ///   focusColor: Colors.orange.withOpacity(0.3),
+  ///   icon: const Icon(Icons.sunny),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
   /// )
   /// ```
   ///
@@ -273,6 +291,10 @@ class IconButton extends StatelessWidget {
   /// ```dart
   /// IconButton(
   ///   hoverColor: Colors.orange.withOpacity(0.3),
+  ///   icon: const Icon(Icons.ac_unit),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
   /// )
   /// ```
   ///
@@ -287,8 +309,10 @@ class IconButton extends StatelessWidget {
   /// ```dart
   /// IconButton(
   ///   color: Colors.blue,
-  ///   onPressed: _handleTap,
+  ///   icon: const Icon(Icons.sunny_snowing),
-  ///   icon: Icon(Icons.widgets),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
   /// )
   /// ```
   final Color? color;
@@ -320,6 +344,10 @@ class IconButton extends StatelessWidget {
   /// ```dart
   /// IconButton(
   ///   highlightColor: Colors.orange.withOpacity(0.3),
+  ///   icon: const Icon(Icons.question_mark),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
   /// )
   /// ```
   ///
@@ -459,8 +487,12 @@ class IconButton extends StatelessWidget {
   ///
   /// ```dart
   /// IconButton(
+  ///   icon: const Icon(Icons.pets),
   ///   style: IconButton.styleFrom(foregroundColor: Colors.green),
-  /// )
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
+  /// ),
   /// ```
   static ButtonStyle styleFrom({
     Color? foregroundColor,

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

@@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
 import 'button_style.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// A [ButtonStyle] that overrides the default appearance of
 /// [IconButton]s when it's used with the [IconButton], the [IconButtonTheme] or the
 /// overall [Theme]'s [ThemeData.iconButtonTheme].

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

@@ -16,6 +16,9 @@ import 'material.dart';
 import 'material_state.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// An ink feature that displays a [color] "splash" in response to a user
 /// gesture that can be confirmed or canceled.
 ///

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

@@ -19,6 +19,9 @@ import 'text_theme.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late Widget _myIcon;
+
 const Duration _kTransitionDuration = Duration(milliseconds: 200);
 const Curve _kTransitionCurve = Curves.fastOutSlowIn;
 const double _kFinalLabelScale = 0.75;
@@ -2877,7 +2880,7 @@ class InputDecoration {
   /// ```dart
   /// prefixIcon: Padding(
   ///   padding: const EdgeInsetsDirectional.only(start: 12.0),
-  ///   child: myIcon, // myIcon is a 48px-wide widget.
+  ///   child: _myIcon, // _myIcon is a 48px-wide widget.
   /// )
   /// ```
   ///
@@ -2999,7 +3002,7 @@ class InputDecoration {
   /// ```dart
   /// suffixIcon: Padding(
   ///   padding: const EdgeInsetsDirectional.only(end: 12.0),
-  ///   child: myIcon, // myIcon is a 48px-wide widget.
+  ///   child: _myIcon, // myIcon is a 48px-wide widget.
   /// )
   /// ```
   ///

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

@@ -18,6 +18,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// int _act = 1;
+
 /// Defines the title font used for [ListTile] descendants of a [ListTileTheme].
 ///
 /// List tiles that appear in a [Drawer] use the theme's [TextTheme.bodyText1]
@@ -166,8 +169,6 @@ enum ListTileControlAffinity {
 /// tapped, the whole row has an ink splash effect (see [InkWell]).
 ///
 /// ```dart
-/// int _act = 1;
-/// // ...
 /// ListTile(
 ///   leading: const Icon(Icons.flight_land),
 ///   title: const Text("Trix's airplane"),

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

@@ -13,6 +13,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Used with [ListTileTheme] to define default property values for
 /// descendant [ListTile] widgets, as well as classes that build
 /// [ListTile]s, like [CheckboxListTile], [RadioListTile], and

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

@@ -10,6 +10,9 @@ import 'constants.dart';
 import 'elevation_overlay.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Signature for the callback used by ink effects to obtain the rectangle for the effect.
 ///
 /// Used by [InkHighlight] and [InkSplash], for example.
@@ -345,7 +348,7 @@ class Material extends StatefulWidget {
   /// Typical usage is as follows:
   ///
   /// ```dart
-  /// MaterialInkController inkController = Material.of(context);
+  /// MaterialInkController? inkController = Material.of(context);
   /// ```
   ///
   /// This method can be expensive (it walks the element tree).

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

@@ -9,6 +9,9 @@ import 'debug.dart';
 import 'time.dart';
 import 'typography.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 // ADDING A NEW STRING
 //
 // If you (someone contributing to the Flutter framework) want to add a new
@@ -28,16 +31,15 @@ import 'typography.dart';
 //
 //    Then you need to add new entries for the string to all of the other
 //    language locale files by running:
-//    ```
+//
-//    dart dev/tools/localization/bin/gen_missing_localizations.dart
+//        dart dev/tools/localization/bin/gen_missing_localizations.dart
-//    ```
+//
 //    Which will copy the english strings into the other locales as placeholders
 //    until they can be translated.
 //
 //    Finally you need to re-generate lib/src/l10n/localizations.dart by running:
-//    ```
+//
-//    dart dev/tools/localization/bin/gen_localizations.dart --overwrite
+//        dart dev/tools/localization/bin/gen_localizations.dart --overwrite
-//    ```
 //
 //    There is a README file with further information in the lib/src/l10n/
 //    directory.
@@ -57,9 +59,8 @@ import 'typography.dart';
 //    strings in lib/src/l10n/material_en.arb.
 //
 //    You also need to re-generate lib/src/l10n/localizations.dart by running:
-//    ```
+//
-//    dart dev/tools/localization/bin/gen_localizations.dart --overwrite
+//        dart dev/tools/localization/bin/gen_localizations.dart --overwrite
-//    ```
 //
 //    This script may result in your updated getters being created in newer
 //    locales and set to the old value of the strings. This is to be expected.
@@ -348,9 +349,9 @@ abstract class MaterialLocalizations {
   /// This getter is compatible with [narrowWeekdays]. For example:
   ///
   /// ```dart
-  /// var localizations = MaterialLocalizations.of(context);
+  ///  MaterialLocalizations localizations = MaterialLocalizations.of(context);
   /// // The name of the first day of week for the current locale.
-  /// var firstDayOfWeek = localizations.narrowWeekdays[localizations.firstDayOfWeekIndex];
+  /// String firstDayOfWeek = localizations.narrowWeekdays[localizations.firstDayOfWeekIndex];
   /// ```
   int get firstDayOfWeekIndex;
 

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

@@ -8,6 +8,9 @@ import 'package:flutter/services.dart';
 
 import 'input_border.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Interactive states that some of the Material widgets can take on when
 /// receiving input from the user.
 ///
@@ -321,30 +324,35 @@ abstract class MaterialStateBorderSide extends BorderSide implements MaterialSta
   /// (the empty set of states) will be used.
   ///
   /// Usage:
+  ///
   /// ```dart
   /// ChipTheme(
   ///   data: Theme.of(context).chipTheme.copyWith(
   ///     side: MaterialStateBorderSide.resolveWith((Set<MaterialState> states) {
   ///       if (states.contains(MaterialState.selected)) {
-  ///         return const BorderSide(width: 1, color: Colors.red);
+  ///         return const BorderSide(color: Colors.red);
   ///       }
   ///       return null;  // Defer to default value on the theme or widget.
   ///     }),
   ///   ),
-  ///   child: Chip(),
+  ///   child: const Chip(
-  /// )
+  ///     label: Text('Transceiver'),
+  ///   ),
+  /// ),
+  /// ```
   ///
-  /// // OR
+  /// Alternatively:
   ///
+  /// ```dart
   /// Chip(
-  ///   ...
+  ///   label: const Text('Transceiver'),
   ///   side: MaterialStateBorderSide.resolveWith((Set<MaterialState> states) {
   ///     if (states.contains(MaterialState.selected)) {
-  ///       return const BorderSide(width: 1, color: Colors.red);
+  ///       return const BorderSide(color: Colors.red);
   ///     }
   ///     return null;  // Defer to default value on the theme or widget.
   ///   }),
-  /// )
+  /// ),
   /// ```
   static MaterialStateBorderSide resolveWith(MaterialPropertyResolver<BorderSide?> callback) =>
       _MaterialStateBorderSide(callback);

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

@@ -17,6 +17,10 @@ import 'text_theme.dart';
 import 'theme.dart';
 import 'tooltip.dart';
 
+// Examples can assume:
+// late BuildContext context;
+// late bool _isDrawerOpen;
+
 /// Material 3 Navigation Bar component.
 ///
 /// Navigation bars offer a persistent and convenient way to switch between
@@ -444,12 +448,25 @@ class _NavigationDestinationInfo extends InheritedWidget {
   /// Which destination index is this in the navigation bar.
   ///
   /// For example:
+  ///
   /// ```dart
   /// NavigationBar(
-  ///   destinations: [
+  ///   destinations: const <Widget>[
-  ///     NavigationDestination(), // This is destination index 0.
+  ///     NavigationDestination(
-  ///     NavigationDestination(), // This is destination index 1.
+  ///       // This is destination index 0.
-  ///     NavigationDestination(), // This is destination index 2.
+  ///       icon: Icon(Icons.surfing),
+  ///       label: 'Surfing',
+  ///     ),
+  ///     NavigationDestination(
+  ///       // This is destination index 1.
+  ///       icon: Icon(Icons.support),
+  ///       label: 'Support',
+  ///     ),
+  ///     NavigationDestination(
+  ///       // This is destination index 2.
+  ///       icon: Icon(Icons.local_hospital),
+  ///       label: 'Hospital',
+  ///     ),
   ///   ]
   /// )
   /// ```
@@ -888,17 +905,18 @@ class _NavigationDestinationLayoutDelegate extends MultiChildLayoutDelegate {
 
 /// Utility Widgets
 
-/// Clamps [MediaQueryData.textScaleFactor] so that if it is greater than
+// Clamps [MediaQueryData.textScaleFactor] so that if it is greater than
-/// [upperLimit] or less than [lowerLimit], [upperLimit] or [lowerLimit] will be
+// [upperLimit] or less than [lowerLimit], [upperLimit] or [lowerLimit] will be
-/// used instead for the [child] widget.
+// used instead for the [child] widget.
-///
+//
-/// Example:
+// Example:
-/// ```
+//
-/// _ClampTextScaleFactor(
+// ```dart
-///   upperLimit: 2.0,
+// _ClampTextScaleFactor(
-///   child: Text('Foo'), // If textScaleFactor is 3.0, this will only scale 2x.
+//   upperLimit: 2.0,
-/// )
+//   child: const Text('Foo'), // If textScaleFactor is 3.0, this will only scale 2x.
-/// ```
+// )
+// ```
 class _ClampTextScaleFactor extends StatelessWidget {
   /// Clamps the text scale factor of descendants by modifying the [MediaQuery]
   /// surrounding [child].
@@ -965,36 +983,36 @@ class _StatusTransitionWidgetBuilder extends StatusTransitionWidget {
   Widget build(BuildContext context) => builder(context, child);
 }
 
-/// Builder widget for widgets that need to be animated from 0 (unselected) to
+// Builder widget for widgets that need to be animated from 0 (unselected) to
-/// 1.0 (selected).
+// 1.0 (selected).
-///
+//
-/// This widget creates and manages an [AnimationController] that it passes down
+// This widget creates and manages an [AnimationController] that it passes down
-/// to the child through the [builder] function.
+// to the child through the [builder] function.
-///
+//
-/// When [isSelected] is `true`, the animation controller will animate from
+// When [isSelected] is `true`, the animation controller will animate from
-/// 0 to 1 (for [duration] time).
+// 0 to 1 (for [duration] time).
-///
+//
-/// When [isSelected] is `false`, the animation controller will animate from
+// When [isSelected] is `false`, the animation controller will animate from
-/// 1 to 0 (for [duration] time).
+// 1 to 0 (for [duration] time).
-///
+//
-/// If [isSelected] is updated while the widget is animating, the animation will
+// If [isSelected] is updated while the widget is animating, the animation will
-/// be reversed until it is either 0 or 1 again. If [alwaysDoFullAnimation] is
+// be reversed until it is either 0 or 1 again. If [alwaysDoFullAnimation] is
-/// true, the animation will reset to 0 or 1 before beginning the animation, so
+// true, the animation will reset to 0 or 1 before beginning the animation, so
-/// that the full animation is done.
+// that the full animation is done.
-///
+//
-/// Usage:
+// Usage:
-/// ```dart
+// ```dart
-/// _SelectableAnimatedBuilder(
+// _SelectableAnimatedBuilder(
-///   isSelected: _isDrawerOpen,
+//   isSelected: _isDrawerOpen,
-///   builder: (context, animation) {
+//   builder: (context, animation) {
-///     return AnimatedIcon(
+//     return AnimatedIcon(
-///       icon: AnimatedIcons.menu_arrow,
+//       icon: AnimatedIcons.menu_arrow,
-///       progress: animation,
+//       progress: animation,
-///       semanticLabel: 'Show menu',
+//       semanticLabel: 'Show menu',
-///     );
+//     );
-///   }
+//   }
-/// )
+// )
-/// ```
+// ```
 class _SelectableAnimatedBuilder extends StatefulWidget {
   /// Builds and maintains an [AnimationController] that will animate from 0 to
   /// 1 and back depending on when [isSelected] is true.

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

@@ -12,6 +12,9 @@ import 'material_state.dart';
 import 'navigation_bar.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [NavigationBar]
 /// widgets.
 ///

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

@@ -11,6 +11,9 @@ import 'package:flutter/widgets.dart';
 import 'navigation_rail.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [NavigationRail]
 /// widgets.
 ///

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

@@ -38,13 +38,14 @@ class _NoSplashFactory extends InteractiveInkFeatureFactory {
 /// Use [NoSplash.splashFactory] to defeat the default ink splash drawn by
 /// an [InkWell] or [ButtonStyle]. For example, to create an [ElevatedButton]
 /// that does not draw the default "ripple" ink splash when it's tapped:
+///
 /// ```dart
 /// ElevatedButton(
 ///   style: ElevatedButton.styleFrom(
 ///     splashFactory: NoSplash.splashFactory,
 ///   ),
 ///   onPressed: () { },
-///   child: Text('No Splash'),
+///   child: const Text('No Splash'),
 /// )
 /// ```
 class NoSplash extends InteractiveInkFeature {

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

@@ -127,10 +127,14 @@ class OutlinedButton extends ButtonStyleButton {
   /// ```dart
   /// OutlinedButton(
   ///   style: OutlinedButton.styleFrom(
-  ///      shape: StadiumBorder(),
+  ///      shape: const StadiumBorder(),
-  ///      side: BorderSide(width: 2, color: Colors.green),
+  ///      side: const BorderSide(width: 2, color: Colors.green),
   ///   ),
-  /// )
+  ///   child: const Text('Seasons of Love'),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
+  /// ),
   /// ```
   static ButtonStyle styleFrom({
     Color? foregroundColor,

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

@@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
 import 'button_style.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// A [ButtonStyle] that overrides the default appearance of
 /// [OutlinedButton]s when it's used with [OutlinedButtonTheme] or with the
 /// overall [Theme]'s [ThemeData.outlinedButtonTheme].

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 import 'material_state.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of the routes used to display popup menus
 /// as well as [PopupMenuItem] and [PopupMenuDivider] widgets.
 ///

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

@@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 @immutable
 /// Defines the visual properties of [ProgressIndicator] widgets.
 ///

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

@@ -12,6 +12,12 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'toggleable.dart';
 
+// Examples can assume:
+// late BuildContext context;
+// enum SingingCharacter { lafayette }
+// late SingingCharacter? _character;
+// late StateSetter setState;
+
 const double _kOuterRadius = 8.0;
 const double _kInnerRadius = 4.5;
 
@@ -116,7 +122,7 @@ class Radio<T> extends StatefulWidget {
   /// Radio<SingingCharacter>(
   ///   value: SingingCharacter.lafayette,
   ///   groupValue: _character,
-  ///   onChanged: (SingingCharacter newValue) {
+  ///   onChanged: (SingingCharacter? newValue) {
   ///     setState(() {
   ///       _character = newValue;
   ///     });

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

@@ -15,6 +15,8 @@ import 'theme_data.dart';
 // Examples can assume:
 // void setState(VoidCallback fn) { }
 // enum Meridiem { am, pm }
+// enum SingingCharacter { lafayette }
+// late SingingCharacter? _character;
 
 /// A [ListTile] with a [Radio]. In other words, a radio button with a label.
 ///
@@ -206,7 +208,7 @@ class RadioListTile<T> extends StatelessWidget {
   ///   title: const Text('Lafayette'),
   ///   value: SingingCharacter.lafayette,
   ///   groupValue: _character,
-  ///   onChanged: (SingingCharacter newValue) {
+  ///   onChanged: (SingingCharacter? newValue) {
   ///     setState(() {
   ///       _character = newValue;
   ///     });

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

@@ -12,6 +12,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [Radio] widgets.
 ///
 /// Descendant widgets obtain the current [RadioThemeData] object using

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

@@ -98,7 +98,7 @@ enum RefreshIndicatorTriggerMode {
 /// ```dart
 /// ListView(
 ///   physics: const AlwaysScrollableScrollPhysics(),
-///   children: ...
+///   // ...
 /// )
 /// ```
 ///

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 import 'material_state.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [Scrollbar] widgets.
 ///
 /// Descendant widgets obtain the current [ScrollbarThemeData] object with

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

@@ -15,6 +15,10 @@ import 'magnifier.dart';
 import 'text_selection.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+// late FocusNode myFocusNode;
+
 /// An eyeballed value that moves the cursor slightly left of where it is
 /// rendered for text on Android so its positioning more accurately matches the
 /// native iOS text cursor positioning.
@@ -313,7 +317,7 @@ class SelectableText extends StatefulWidget {
   /// to the [focusNode]:
   ///
   /// ```dart
-  /// focusNode.addListener(() { print(myFocusNode.hasFocus); });
+  /// myFocusNode.addListener(() { print(myFocusNode.hasFocus); });
   /// ```
   ///
   /// If null, this widget will create its own [FocusNode] with

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

@@ -15,6 +15,9 @@ import 'text_button.dart';
 import 'text_button_theme.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 const double _singleLineVerticalPadding = 14.0;
 
 // TODO(ianh): We should check if the given text and actions are going to fit on
@@ -40,9 +43,11 @@ const Curve _snackBarFadeOutCurve = Interval(0.72, 1.0, curve: Curves.fastOutSlo
 ///
 /// ```dart
 /// ScaffoldMessenger.of(context).showSnackBar(
-///   SnackBar( ... )
+///   const SnackBar(
+///     content: Text('He likes me. I think he likes me.'),
+///   )
 /// ).closed.then((SnackBarClosedReason reason) {
-///    ...
+///    // ...
 /// });
 /// ```
 enum SnackBarClosedReason {
@@ -256,29 +261,29 @@ class SnackBar extends StatefulWidget {
   /// The amount of padding to apply to the snack bar's content and optional
   /// action.
   ///
-  /// If this property is null, the default padding values for:
+  /// If this property is null, the default padding values are as follows:
   ///
   /// * [content]
   ///     * Top and bottom paddings are 14.
   ///     * Left padding is 24 if [behavior] is [SnackBarBehavior.fixed],
-  ///       16 if [behavior] is [SnackBarBehavior.floating]
+  ///       16 if [behavior] is [SnackBarBehavior.floating].
-  ///     * Right padding is same as start padding if there is no [action], otherwise 0.
+  ///     * Right padding is same as start padding if there is no [action],
+  ///       otherwise 0.
   /// * [action]
-  ///     * Top and bottom paddings are 14
+  ///     * Top and bottom paddings are 14.
   ///     * Left and right paddings are half of [content]'s left padding.
   ///
-  /// If this property is not null, the padding assignment for:
+  /// If this property is not null, the padding is as follows:
   ///
   /// * [content]
   ///     * Left, top and bottom paddings are assigned normally.
-  ///     * Right padding is assigned normally if there is no [action], otherwise 0.
+  ///     * Right padding is assigned normally if there is no [action],
+  ///       otherwise 0.
   /// * [action]
-  ///     * Left padding is replaced with half value of right padding.
+  ///     * Left padding is replaced with half the right padding.
   ///     * Top and bottom paddings are assigned normally.
-  ///     * Right padding has an additional half value of right padding.
+  ///     * Right padding is replaced with one and a half times the
-  ///       ```dart
+  ///       right padding.
-  ///       right + (right / 2)
-  ///       ```
   final EdgeInsetsGeometry? padding;
 
   /// The width of the snack bar.

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

@@ -17,6 +17,10 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'toggleable.dart';
 
+// Examples can assume:
+// bool _giveVerse = true;
+// late StateSetter setState;
+
 const double _kTrackHeight = 14.0;
 const double _kTrackWidth = 33.0;
 const double _kTrackRadius = _kTrackHeight / 2.0;

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

@@ -12,6 +12,9 @@ import 'material_state.dart';
 import 'theme.dart';
 import 'theme_data.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines default property values for descendant [Switch] widgets.
 ///
 /// Descendant widgets obtain the current [SwitchThemeData] object using

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

@@ -302,7 +302,9 @@ class _TabControllerScope extends InheritedWidget {
 ///
 /// ```dart
 /// class MyDemo extends StatelessWidget {
-///   final List<Tab> myTabs = <Tab>[
+///   const MyDemo({super.key});
+///
+///   static const List<Tab> myTabs = <Tab>[
 ///     Tab(text: 'LEFT'),
 ///     Tab(text: 'RIGHT'),
 ///   ];
@@ -313,13 +315,13 @@ class _TabControllerScope extends InheritedWidget {
 ///       length: myTabs.length,
 ///       child: Scaffold(
 ///         appBar: AppBar(
-///           bottom: TabBar(
+///           bottom: const TabBar(
 ///             tabs: myTabs,
 ///           ),
 ///         ),
 ///         body: TabBarView(
 ///           children: myTabs.map((Tab tab) {
-///             final String label = tab.text.toLowerCase();
+///             final String label = tab.text!.toLowerCase();
 ///             return Center(
 ///               child: Text(
 ///                 'This is the $label tab',

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

@@ -843,6 +843,7 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// Use [NoSplash.splashFactory] to defeat ink splash rendering. For example
   /// to defeat both the splash and the hover/pressed overlay, but not the
   /// keyboard focused overlay:
+  ///
   /// ```dart
   /// TabBar(
   ///   splashFactory: NoSplash.splashFactory,
@@ -851,7 +852,9 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   ///       return states.contains(MaterialState.focused) ? null : Colors.transparent;
   ///     },
   ///   ),
-  ///   ...
+  ///   tabs: const <Widget>[
+  ///     // ...
+  ///   ],
   /// )
   /// ```
   final InteractiveInkFeatureFactory? splashFactory;
@@ -859,13 +862,16 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
   /// Defines the clipping radius of splashes that extend outside the bounds of the tab.
   ///
   /// This can be useful to match the [BoxDecoration.borderRadius] provided as [indicator].
+  ///
   /// ```dart
   /// TabBar(
   ///   indicator: BoxDecoration(
   ///     borderRadius: BorderRadius.circular(40),
   ///   ),
   ///   splashBorderRadius: BorderRadius.circular(40),
-  ///   ...
+  ///   tabs: const <Widget>[
+  ///     // ...
+  ///   ],
   /// )
   /// ```
   ///

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

@@ -137,7 +137,11 @@ class TextButton extends ButtonStyleButton {
   /// ```dart
   /// TextButton(
   ///   style: TextButton.styleFrom(foregroundColor: Colors.green),
-  /// )
+  ///   child: const Text('Give Kate a mix tape'),
+  ///   onPressed: () {
+  ///     // ...
+  ///   },
+  /// ),
   /// ```
   static ButtonStyle styleFrom({
     Color? foregroundColor,

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

@@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
 import 'button_style.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// A [ButtonStyle] that overrides the default appearance of
 /// [TextButton]s when it's used with [TextButtonTheme] or with the
 /// overall [Theme]'s [ThemeData.textButtonTheme].

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

@@ -23,6 +23,10 @@ import 'theme.dart';
 
 export 'package:flutter/services.dart' show SmartDashesType, SmartQuotesType, TextCapitalization, TextInputAction, TextInputType;
 
+// Examples can assume:
+// late BuildContext context;
+// late FocusNode myFocusNode;
+
 /// Signature for the [TextField.buildCounter] callback.
 typedef InputCounterWidgetBuilder = Widget? Function(
   /// The build context for the TextField.
@@ -427,7 +431,7 @@ class TextField extends StatefulWidget {
   /// to the [focusNode]:
   ///
   /// ```dart
-  /// focusNode.addListener(() { print(myFocusNode.hasFocus); });
+  /// myFocusNode.addListener(() { print(myFocusNode.hasFocus); });
   /// ```
   ///
   /// If null, this widget will create its own [FocusNode].

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

@@ -7,6 +7,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties needed for text selection in [TextField] and
 /// [SelectableText] widgets.
 ///

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

@@ -32,22 +32,22 @@ import 'typography.dart';
 /// bodyText1 and bodyText2.
 ///
 /// The 2018 spec has thirteen text styles:
-/// ```
+///
-/// NAME         SIZE  WEIGHT  SPACING
+/// | NAME       | SIZE |  WEIGHT |  SPACING |             |
-/// headline1    96.0  light   -1.5
+/// |------------|------|---------|----------|-------------|
-/// headline2    60.0  light   -0.5
+/// | headline1  | 96.0 | light   | -1.5     |             |
-/// headline3    48.0  regular  0.0
+/// | headline2  | 60.0 | light   | -0.5     |             |
-/// headline4    34.0  regular  0.25
+/// | headline3  | 48.0 | regular |  0.0     |             |
-/// headline5    24.0  regular  0.0
+/// | headline4  | 34.0 | regular |  0.25    |             |
-/// headline6    20.0  medium   0.15
+/// | headline5  | 24.0 | regular |  0.0     |             |
-/// subtitle1    16.0  regular  0.15
+/// | headline6  | 20.0 | medium  |  0.15    |             |
-/// subtitle2    14.0  medium   0.1
+/// | subtitle1  | 16.0 | regular |  0.15    |             |
-/// body1        16.0  regular  0.5   (bodyText1)
+/// | subtitle2  | 14.0 | medium  |  0.1     |             |
-/// body2        14.0  regular  0.25  (bodyText2)
+/// | body1      | 16.0 | regular |  0.5     | (bodyText1) |
-/// button       14.0  medium   1.25
+/// | body2      | 14.0 | regular |  0.25    | (bodyText2) |
-/// caption      12.0  regular  0.4
+/// | button     | 14.0 | medium  |  1.25    |             |
-/// overline     10.0  regular  1.5
+/// | caption    | 12.0 | regular |  0.4     |             |
-/// ```
+/// | overline   | 10.0 | regular |  1.5     |             |
 ///
 /// ...where "light" is `FontWeight.w300`, "regular" is `FontWeight.w400` and
 /// "medium" is `FontWeight.w500`.

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

@@ -89,7 +89,7 @@ class Theme extends StatelessWidget {
   /// Widget build(BuildContext context) {
   ///   return MaterialApp(
   ///     theme: ThemeData.light(),
-  ///     body: Builder(
+  ///     home: Builder(
   ///       // Create an inner BuildContext so that we can refer to
   ///       // the Theme with Theme.of().
   ///       builder: (BuildContext context) {

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

@@ -57,6 +57,9 @@ import 'typography.dart';
 
 export 'package:flutter/services.dart' show Brightness;
 
+// Examples can assume:
+// late BuildContext context;
+
 /// An interface that defines custom additions to a [ThemeData] object.
 ///
 /// Typically used for custom colors. To use, subclass [ThemeExtension],
@@ -1576,9 +1579,10 @@ class ThemeData with Diagnosticable {
   ///
   /// ```dart
   /// final ThemeData theme = Theme.of(context);
-  /// theme.textTheme.headline1.copyWith(
+  /// final TextStyle style = theme.textTheme.headline1!.copyWith(
   ///   color: theme.colorScheme.onSecondary,
-  /// )
+  /// );
+  /// // ...use style...
   /// ```
   @Deprecated(
     'No longer used by the framework, please remove any reference to it. '

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

@@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
 import 'input_decorator.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of the widget displayed with [showTimePicker].
 ///
 /// Descendant widgets obtain the current [TimePickerThemeData] object using
@@ -133,7 +136,8 @@ class TimePickerThemeData with Diagnosticable {
   /// The color of the entry mode [IconButton].
   ///
   /// If this is null, the time picker defaults to:
-  /// ```
+  ///
+  /// ```dart
   /// Theme.of(context).colorScheme.onSurface.withOpacity(
   ///   Theme.of(context).colorScheme.brightness == Brightness.dark ? 1.0 : 0.6,
   /// )
@@ -173,8 +177,9 @@ class TimePickerThemeData with Diagnosticable {
   /// The shape of the day period that the time picker uses.
   ///
   /// If this is null, the time picker defaults to:
-  /// ```
+  ///
-  /// RoundedRectangleBorder(
+  /// ```dart
+  /// const RoundedRectangleBorder(
   ///   borderRadius: BorderRadius.all(Radius.circular(4.0)),
   ///   side: BorderSide(),
   /// )
@@ -184,10 +189,14 @@ class TimePickerThemeData with Diagnosticable {
   /// The color and weight of the day period's outline.
   ///
   /// If this is null, the time picker defaults to:
-  /// ```
+  ///
+  /// ```dart
   /// BorderSide(
-  ///   color: Color.alphaBlend(colorScheme.onBackground.withOpacity(0.38), colorScheme.surface),
+  ///   color: Color.alphaBlend(
-  /// )
+  ///     Theme.of(context).colorScheme.onBackground.withOpacity(0.38),
+  ///     Theme.of(context).colorScheme.surface,
+  ///   ),
+  /// ),
   /// ```
   final BorderSide? dayPeriodBorderSide;
 

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

@@ -18,6 +18,10 @@ import 'theme.dart';
 import 'theme_data.dart';
 import 'toggle_buttons_theme.dart';
 
+// Examples can assume:
+// List<bool> isSelected = <bool>[];
+// void setState(dynamic arg) { }
+
 /// A set of toggle buttons.
 ///
 /// The list of [children] are laid out along [direction]. The state of each button
@@ -43,34 +47,32 @@ import 'toggle_buttons_theme.dart';
 /// Here is an implementation that allows for multiple buttons to be
 /// simultaneously selected, while requiring none of the buttons to be
 /// selected.
+///
 /// ```dart
 /// ToggleButtons(
-///   children: <Widget>[
+///   isSelected: isSelected,
-///     Icon(Icons.ac_unit),
-///     Icon(Icons.call),
-///     Icon(Icons.cake),
-///   ],
 ///   onPressed: (int index) {
 ///     setState(() {
 ///       isSelected[index] = !isSelected[index];
 ///     });
 ///   },
-///   isSelected: isSelected,
+///   children: const <Widget>[
+///     Icon(Icons.ac_unit),
+///     Icon(Icons.call),
+///     Icon(Icons.cake),
+///   ],
 /// ),
 /// ```
 ///
 /// {@animation 700 150 https://flutter.github.io/assets-for-api-docs/assets/material/toggle_buttons_required_mutually_exclusive.mp4}
 ///
-/// Here is an implementation that requires mutually exclusive selection
+/// Here is an implementation that requires mutually exclusive selection while
-/// while requiring at least one selection. Note that this assumes that
+/// requiring at least one selection. This assumes that [isSelected] was
-/// [isSelected] was properly initialized with one selection.
+/// properly initialized with one selection.
+///
 /// ```dart
 /// ToggleButtons(
-///   children: <Widget>[
+///   isSelected: isSelected,
-///     Icon(Icons.ac_unit),
-///     Icon(Icons.call),
-///     Icon(Icons.cake),
-///   ],
 ///   onPressed: (int index) {
 ///     setState(() {
 ///       for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
@@ -82,7 +84,11 @@ import 'toggle_buttons_theme.dart';
 ///       }
 ///     });
 ///   },
-///   isSelected: isSelected,
+///   children: const <Widget>[
+///     Icon(Icons.ac_unit),
+///     Icon(Icons.call),
+///     Icon(Icons.cake),
+///   ],
 /// ),
 /// ```
 ///
@@ -90,13 +96,10 @@ import 'toggle_buttons_theme.dart';
 ///
 /// Here is an implementation that requires mutually exclusive selection,
 /// but allows for none of the buttons to be selected.
+///
 /// ```dart
 /// ToggleButtons(
-///   children: <Widget>[
+///   isSelected: isSelected,
-///     Icon(Icons.ac_unit),
-///     Icon(Icons.call),
-///     Icon(Icons.cake),
-///   ],
 ///   onPressed: (int index) {
 ///     setState(() {
 ///       for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
@@ -108,37 +111,42 @@ import 'toggle_buttons_theme.dart';
 ///       }
 ///     });
 ///   },
-///   isSelected: isSelected,
+///   children: const <Widget>[
+///     Icon(Icons.ac_unit),
+///     Icon(Icons.call),
+///     Icon(Icons.cake),
+///   ],
 /// ),
 /// ```
 ///
 /// {@animation 700 150 https://flutter.github.io/assets-for-api-docs/assets/material/toggle_buttons_required.mp4}
 ///
 /// Here is an implementation that allows for multiple buttons to be
-/// simultaneously selected, while requiring at least one selection. Note
+/// simultaneously selected, while requiring at least one selection. This
-/// that this assumes that [isSelected] was properly initialized with one
+/// assumes that [isSelected] was properly initialized with one selection.
-/// selection.
+///
 /// ```dart
 /// ToggleButtons(
-///   children: <Widget>[
+///   isSelected: isSelected,
-///     Icon(Icons.ac_unit),
-///     Icon(Icons.call),
-///     Icon(Icons.cake),
-///   ],
 ///   onPressed: (int index) {
 ///     int count = 0;
-///     isSelected.forEach((bool val) {
+///     for (final bool value in isSelected) {
-///       if (val) count++;
+///       if (value) {
-///     });
+///         count += 1;
-///
+///       }
-///     if (isSelected[index] && count < 2)
+///     }
+///     if (isSelected[index] && count < 2) {
 ///       return;
-///
+///     }
 ///     setState(() {
 ///       isSelected[index] = !isSelected[index];
 ///     });
 ///   },
-///   isSelected: isSelected,
+///   children: const <Widget>[
+///     Icon(Icons.ac_unit),
+///     Icon(Icons.call),
+///     Icon(Icons.cake),
+///   ],
 /// ),
 /// ```
 ///

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

@@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the color and border properties of [ToggleButtons] widgets.
 ///
 /// Used by [ToggleButtonsTheme] to control the color and border properties
@@ -263,7 +266,7 @@ class ToggleButtonsTheme extends InheritedTheme {
   /// Typical usage is as follows:
   ///
   /// ```dart
-  /// ToggleButtonsTheme theme = ToggleButtonsTheme.of(context);
+  /// ToggleButtonsThemeData theme = ToggleButtonsTheme.of(context);
   /// ```
   static ToggleButtonsThemeData of(BuildContext context) {
     final ToggleButtonsTheme? toggleButtonsTheme = context.dependOnInheritedWidgetOfExactType<ToggleButtonsTheme>();

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

@@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
 
 import 'theme.dart';
 
+// Examples can assume:
+// late BuildContext context;
+
 /// Defines the visual properties of [Tooltip] widgets.
 ///
 /// Used by [TooltipTheme] to control the visual properties of tooltips in a

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

@@ -8,6 +8,9 @@ import 'package:flutter/painting.dart';
 import 'colors.dart';
 import 'text_theme.dart';
 
+// Examples can assume:
+// late TargetPlatform platform;
+
 /// A characterization of the of a [TextTheme]'s glyphs that is used to define
 /// its localized [TextStyle] geometry for [ThemeData.textTheme].
 ///

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

@@ -8,6 +8,9 @@ import 'basic_types.dart';
 import 'edge_insets.dart';
 import 'image_provider.dart';
 
+// Examples can assume:
+// late Decoration myDecoration;
+
 // This group of classes is intended for painting in cartesian coordinates.
 
 /// A description of a box decoration (a decoration applied to a [Rect]).

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

@@ -1162,11 +1162,9 @@ class MemoryImage extends ImageProvider<MemoryImage> {
 /// bundled, the app has to specify which ones to include. For instance a
 /// package named `fancy_backgrounds` could have:
 ///
-/// ```
+///     lib/backgrounds/background1.png
-/// lib/backgrounds/background1.png
+///     lib/backgrounds/background2.png
-/// lib/backgrounds/background2.png
+///     lib/backgrounds/background3.png
-/// lib/backgrounds/background3.png
-/// ```
 ///
 /// To include, say the first image, the `pubspec.yaml` of the app should specify
 /// it in the `assets` section:

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

@@ -40,11 +40,9 @@ const double _kLowDprLimit = 2.0;
 /// as 2.0 and 4.0 pixel ratios (variants). The asset bundle should then
 /// contain the following assets:
 ///
-/// ```
+///     heart.png
-/// heart.png
+///     2.0x/heart.png
-/// 2.0x/heart.png
+///     4.0x/heart.png
-/// 4.0x/heart.png
-/// ```
 ///
 /// On a device with a 1.0 device pixel ratio, the image chosen would be
 /// heart.png; on a device with a 2.0 device pixel ratio, the image chosen
@@ -88,16 +86,13 @@ const double _kLowDprLimit = 2.0;
 /// at the equivalent level; that is, the following is also a valid bundle
 /// structure:
 ///
-/// ```
+///     icons/heart.png
-/// icons/heart.png
+///     icons/1.5x/heart.png
-/// icons/1.5x/heart.png
+///     icons/2.0x/heart.png
-/// icons/2.0x/heart.png
-/// ```
 ///
 /// assets/icons/3.0x/heart.png would be a valid variant of
 /// assets/icons/heart.png.
 ///
-///
 /// ## Fetching assets
 ///
 /// When fetching an image provided by the app itself, use the [assetName]
@@ -113,7 +108,7 @@ const double _kLowDprLimit = 2.0;
 ///
 /// Then, to fetch the image, use:
 /// ```dart
-/// AssetImage('icons/heart.png')
+/// const AssetImage('icons/heart.png')
 /// ```
 ///
 /// {@tool snippet}
@@ -204,7 +199,7 @@ const double _kLowDprLimit = 2.0;
 /// `my_icons`. Then to fetch the image, use:
 ///
 /// ```dart
-/// AssetImage('icons/heart.png', package: 'my_icons')
+/// const AssetImage('icons/heart.png', package: 'my_icons')
 /// ```
 ///
 /// Assets used by the package itself should also be fetched using the [package]
@@ -219,11 +214,9 @@ const double _kLowDprLimit = 2.0;
 /// bundled, the app has to specify which ones to include. For instance a
 /// package named `fancy_backgrounds` could have:
 ///
-/// ```
+///     lib/backgrounds/background1.png
-/// lib/backgrounds/background1.png
+///     lib/backgrounds/background2.png
-/// lib/backgrounds/background2.png
+///     lib/backgrounds/background3.png
-/// lib/backgrounds/background3.png
-/// ```
 ///
 /// To include, say the first image, the `pubspec.yaml` of the app should specify
 /// it in the `assets` section:

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

@@ -62,9 +62,11 @@ class ImageInfo {
   /// {@tool snippet}
   ///
   /// The following sample shows how to appropriately check whether the
-  /// [ImageInfo] reference refers to new image data or not.
+  /// [ImageInfo] reference refers to new image data or not (in this case in a
+  /// setter).
   ///
   /// ```dart
+  /// ImageInfo? get imageInfo => _imageInfo;
   /// ImageInfo? _imageInfo;
   /// set imageInfo (ImageInfo? value) {
   ///   // If the image reference is exactly the same, do nothing.
@@ -78,9 +80,12 @@ class ImageInfo {
   ///     value.dispose();
   ///     return;
   ///   }
+  ///   // It is a new image. Dispose of the old one and take a reference
+  ///   // to the new one.
   ///   _imageInfo?.dispose();
   ///   _imageInfo = value;
-  ///   // Perform work to determine size, or paint the image.
+  ///   // Perform work to determine size, paint the image, etc.
+  ///   // ...
   /// }
   /// ```
   /// {@end-tool}

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

@@ -12,6 +12,9 @@ import 'text_painter.dart';
 import 'text_span.dart';
 import 'text_style.dart';
 
+// Examples can assume:
+// late InlineSpan myInlineSpan;
+
 /// Mutable wrapper of an integer that can be passed by reference to track a
 /// value across a recursive stack.
 class Accumulator {

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

@@ -235,12 +235,12 @@ class MatrixUtils {
     // First, consider that a full point transform using the vector math
     // package involves expanding it out into a vector3 with a Z coordinate
     // of 0.0 and then performing 3 multiplies and 3 adds per coordinate:
-    // ```
+    //
-    // xt = x*m00 + y*m10 + z*m20 + m30;
+    //     xt = x*m00 + y*m10 + z*m20 + m30;
-    // yt = x*m01 + y*m11 + z*m21 + m31;
+    //     yt = x*m01 + y*m11 + z*m21 + m31;
-    // zt = x*m02 + y*m12 + z*m22 + m32;
+    //     zt = x*m02 + y*m12 + z*m22 + m32;
-    // wt = x*m03 + y*m13 + z*m23 + m33;
+    //     wt = x*m03 + y*m13 + z*m23 + m33;
-    // ```
+    //
     // Immediately we see that we can get rid of the 3rd column of multiplies
     // since we know that Z=0.0. We can also get rid of the 3rd row because
     // we ignore the resulting Z coordinate. Finally we can get rid of the
@@ -307,26 +307,26 @@ class MatrixUtils {
     // you combine both of them, the resulting "opposite corner" will
     // actually be between the limits they established by pushing the walls
     // away from each other, as below:
-    // ```
+    //
-    //         +---------(originx,originy)--------------+
+    //             +---------(originx,originy)--------------+
-    //         |            -----^----                  |
+    //             |            -----^----                  |
-    //         |       -----          ----              |
+    //             |       -----          ----              |
-    //         |  -----                   ----          |
+    //             |  -----                   ----          |
-    // (+hx,+hy)<                             ----      |
+    //     (+hx,+hy)<                             ----      |
-    //         |  ----                            ----  |
+    //             |  ----                            ----  |
-    //         |      ----                             >(+wx,+wy)
+    //             |      ----                             >(+wx,+wy)
-    //         |          ----                   -----  |
+    //             |          ----                   -----  |
-    //         |              ----          -----       |
+    //             |              ----          -----       |
-    //         |                  ---- -----            |
+    //             |                  ---- -----            |
-    //         |                      v                 |
+    //             |                      v                 |
-    //         +---------------(+wx+hx,+wy+hy)----------+
+    //             +---------------(+wx+hx,+wy+hy)----------+
-    // ```
+    //
     // In this diagram, consider that:
-    // ```
+    //
-    // wx would be a positive number
+    //  * wx would be a positive number
-    // hx would be a negative number
+    //  * hx would be a negative number
-    // wy and hy would both be positive numbers
+    //  * wy and hy would both be positive numbers
-    // ```
+    //
     // As a result, wx pushes out the right wall, hx pushes out the left wall,
     // and both wy and hy push down the bottom wall of the bounding box. The
     // wx,hx pair (of opposite signs) worked on opposite walls and the final

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

@@ -12,6 +12,9 @@ import 'basic_types.dart';
 import 'inline_span.dart';
 import 'text_painter.dart';
 
+// Examples can assume:
+// late TextSpan myTextSpan;
+
 /// An immutable span of text.
 ///
 /// A [TextSpan] object can be styled using its [style] property. The style will
@@ -214,7 +217,7 @@ class TextSpan extends InlineSpan implements HitTestTarget, MouseTrackerAnnotati
   /// text value:
   ///
   /// ```dart
-  /// TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
+  /// const TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
   /// ```
   final String? semanticsLabel;
 

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

@@ -357,9 +357,7 @@ const double _kDefaultFontSize = 14.0;
 /// the app can use these selectively when declaring a font. Suppose a package
 /// named `my_package` has:
 ///
-/// ```
+///     lib/fonts/Raleway-Medium.ttf
-/// lib/fonts/Raleway-Medium.ttf
-/// ```
 ///
 /// Then the app can declare a font like in the example below:
 ///
@@ -790,9 +788,9 @@ class TextStyle with Diagnosticable {
   /// For example, to control the weight axis of the Roboto Slab variable font
   /// (https://fonts.google.com/specimen/Roboto+Slab):
   /// ```dart
-  /// TextStyle(
+  /// const TextStyle(
   ///   fontFamily: 'RobotoSlab',
-  ///   fontVariations: <FontVariation>[FontVariation('wght', 900.0)]
+  ///   fontVariations: <ui.FontVariation>[ui.FontVariation('wght', 900.0)]
   /// )
   /// ```
   final List<ui.FontVariation>? fontVariations;

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

@@ -14,6 +14,11 @@ import 'package:vector_math/vector_math_64.dart';
 import 'debug.dart';
 import 'object.dart';
 
+// Examples can assume:
+// abstract class RenderBar extends RenderBox { }
+// late RenderBox firstChild;
+// void markNeedsLayout() { }
+
 // This class should only be used in debug builds.
 class _DebugSize extends Size {
   _DebugSize(super.source, this._owner, this._canBeUsedByParent) : super.copy();
@@ -994,11 +999,12 @@ class _IntrinsicDimensionsCacheEntry {
 ///
 /// ```dart
 /// AxisDirection get axis => _axis;
-/// AxisDirection _axis;
+/// AxisDirection _axis = AxisDirection.down; // or initialized in constructor
 /// set axis(AxisDirection value) {
-///   assert(value != null); // same check as in the constructor
+///   assert(value != null); // same checks as in the constructor
-///   if (value == _axis)
+///   if (value == _axis) {
 ///     return;
+///   }
 ///   _axis = value;
 ///   markNeedsLayout();
 /// }
@@ -1135,6 +1141,7 @@ class _IntrinsicDimensionsCacheEntry {
 /// The declaration of the `RenderFoo` class itself would thus look like this:
 ///
 /// ```dart
+/// // continuing from previous example...
 /// class RenderFoo extends RenderBox with
 ///   ContainerRenderObjectMixin<RenderBox, FooParentData>,
 ///   RenderBoxContainerDefaultsMixin<RenderBox, FooParentData> {
@@ -1148,9 +1155,10 @@ class _IntrinsicDimensionsCacheEntry {
 /// children's [parentData] fields):
 ///
 /// ```dart
-/// RenderBox child = firstChild;
+/// // continuing from previous example...
+/// RenderBox? child = firstChild;
 /// while (child != null) {
-///   final FooParentData childParentData = child.parentData;
+///   final FooParentData childParentData = child.parentData! as FooParentData;
 ///   // ...operate on child and childParentData...
 ///   assert(child.parentData == childParentData);
 ///   child = childParentData.nextSibling;
@@ -2675,10 +2683,16 @@ abstract class RenderBox extends RenderObject {
   /// so that they support [debugPaintPointersEnabled]:
   ///
   /// ```dart
-  /// @override
+  /// class RenderFoo extends RenderBox {
-  /// void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///   // ...
-  ///   assert(debugHandleEvent(event, entry));
+  ///
-  ///   // ... handle the event ...
+  ///   @override
+  ///   void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///     assert(debugHandleEvent(event, entry));
+  ///     // ... handle the event ...
+  ///   }
+  ///
+  ///   // ...
   /// }
   /// ```
   @override
@@ -2694,10 +2708,16 @@ abstract class RenderBox extends RenderObject {
   /// [debugHandleEvent] from their [handleEvent] method, as follows:
   ///
   /// ```dart
-  /// @override
+  /// class RenderFoo extends RenderBox {
-  /// void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///   // ...
-  ///   assert(debugHandleEvent(event, entry));
+  ///
-  ///   // ... handle the event ...
+  ///   @override
+  ///   void handleEvent(PointerEvent event, HitTestEntry entry) {
+  ///     assert(debugHandleEvent(event, entry));
+  ///     // ... handle the event ...
+  ///   }
+  ///
+  ///   // ...
   /// }
   /// ```
   ///

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

@@ -6,6 +6,10 @@ import 'dart:async';
 
 import 'system_channels.dart';
 
+// Examples can assume:
+// // so that we can import the fake "split_component.dart" in an example below:
+// // ignore_for_file: uri_does_not_exist
+
 /// Manages the installation and loading of deferred components.
 ///
 /// Deferred components allow Flutter applications to download precompiled AOT
@@ -41,13 +45,17 @@ class DeferredComponent {
   /// the assets from a component with both dart code and assets. Deferred components
   /// containing dart code should call `loadLibrary()` on a deferred imported
   /// library's prefix to ensure that the dart code is properly loaded as
-  /// `loadLibrary()` will provide the loading unit id needed for the dart
+  /// `loadLibrary()` will provide the loading unit ID needed for the Dart
   /// library loading process. For example:
   ///
   /// ```dart
-  /// import 'split_component.dart' deferred as SplitComponent;
+  /// import 'split_component.dart' deferred as split_component;
-  /// ...
+  /// // ...
-  /// SplitComponent.loadLibrary();
+  /// void _showSplit() {
+  ///   // ...
+  ///   split_component.loadLibrary();
+  ///   // ...
+  /// }
   /// ```
   ///
   /// This method will not load associated dart libraries contained in the component,
@@ -60,9 +68,9 @@ class DeferredComponent {
   /// See also:
   ///
   ///  * [uninstallDeferredComponent], a method to request the uninstall of a component.
-  ///  * [loadLibrary](https://api.dart.dev/dart-mirrors/LibraryDependencyMirror/loadLibrary.html),
+  ///  * [loadLibrary](https://dart.dev/guides/language/language-tour#lazily-loading-a-library),
-  ///    the dart method to trigger the installation of the corresponding deferred component that
+  ///    the Dart method to trigger the installation of the corresponding deferred component that
-  ///    contains the dart library.
+  ///    contains the Dart library.
   static Future<void> installDeferredComponent({required String componentName}) async {
     await SystemChannels.deferredComponent.invokeMethod<void>(
       'installDeferredComponent',

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

@@ -137,7 +137,7 @@ class PlatformException implements Exception {
   ///
   /// ```dart
   /// try {
-  ///   ...
+  ///   // ...
   /// } catch (e, stacktrace) {
   ///   print(stacktrace);
   /// }

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

@@ -409,7 +409,7 @@ class SystemChannels {
   ///    a list of [MenuItem]s, and ends up looking like this example:
   ///
   /// ```dart
-  /// List<Map<String, Object?>> menu = <String, Object?>{
+  /// Map<String, Object?> menu = <String, Object?>{
   ///   '0': <Map<String, Object?>>[
   ///     <String, Object?>{
   ///       'id': 1,

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

@@ -14,6 +14,14 @@ export 'package:flutter/foundation.dart' show TargetPlatform;
 
 export 'text_input.dart' show TextEditingValue;
 
+// Examples can assume:
+// late RegExp _pattern;
+
+/// Mechanisms for enforcing maximum length limits.
+///
+/// This is used by [TextField] to specify how the [TextField.maxLength] should
+/// be applied.
+///
 /// {@template flutter.services.textFormatter.maxLengthEnforcement}
 /// ### [MaxLengthEnforcement.enforced] versus
 /// [MaxLengthEnforcement.truncateAfterCompositionEnds]
@@ -40,8 +48,8 @@ export 'text_input.dart' show TextEditingValue;
 /// See also:
 ///
 ///  * [TextField.maxLengthEnforcement] which is used in conjunction with
-///  [TextField.maxLength] to limit the length of user input. [TextField] also
+///    [TextField.maxLength] to limit the length of user input. [TextField] also
-///  provides a character counter to provide visual feedback.
+///    provides a character counter to provide visual feedback.
 enum MaxLengthEnforcement {
   /// No enforcement applied to the editing value. It's possible to exceed the
   /// max length.
@@ -227,9 +235,16 @@ class _TextEditingValueAccumulator {
 /// [TextEditingValue] and falls back to the current [TextEditingValue] when the
 /// given [filterPattern] fails to match. Consider using a different
 /// [TextInputFormatter] such as:
+///
 /// ```dart
-/// TextInputFormatter.withFunction((oldValue, newValue) => regExp.hasMatch(newValue.text) ? newValue : oldValue)
+/// // _pattern is a RegExp or other Pattern object
+/// TextInputFormatter.withFunction(
+///   (TextEditingValue oldValue, TextEditingValue newValue) {
+///     return _pattern.hasMatch(newValue.text) ? newValue : oldValue;
+///   },
+/// ),
 /// ```
+///
 /// for accepting/rejecting new input based on a predicate on the full string.
 /// As an example, [FilteringTextInputFormatter] typically shouldn't be used
 /// with [RegExp]s that contain positional matchers (`^` or `$`) since these

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

@@ -1248,17 +1248,22 @@ mixin DeltaTextInputClient implements TextInputClient {
   /// This example shows what an implementation of this method could look like.
   ///
   /// ```dart
-  /// TextEditingValue? _localValue;
+  /// class MyClient with DeltaTextInputClient {
-  /// @override
+  ///   TextEditingValue? _localValue;
-  /// void updateEditingValueWithDeltas(List<TextEditingDelta> textEditingDeltas) {
+  ///
-  ///   if (_localValue == null) {
+  ///   @override
-  ///     return;
+  ///   void updateEditingValueWithDeltas(List<TextEditingDelta> textEditingDeltas) {
+  ///     if (_localValue == null) {
+  ///       return;
+  ///     }
+  ///     TextEditingValue newValue = _localValue!;
+  ///     for (final TextEditingDelta delta in textEditingDeltas) {
+  ///       newValue = delta.apply(newValue);
+  ///     }
+  ///     _localValue = newValue;
   ///   }
-  ///   TextEditingValue newValue = _localValue!;
+  ///
-  ///   for (final TextEditingDelta delta in textEditingDeltas) {
+  ///   // ...
-  ///     newValue = delta.apply(newValue);
-  ///   }
-  ///   _localValue = newValue;
   /// }
   /// ```
   /// {@end-tool}

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

@@ -260,12 +260,12 @@ abstract class Action<T extends Intent> with Diagnosticable {
   /// changing the return type of the override to match the type of the returned
   /// value provides more type safety.
   ///
-  /// For instance, if your override of `invoke` returns an `int`, then define
+  /// For instance, if an override of `invoke` returned an `int`, then it might
-  /// it like so:
+  /// be defined like so:
   ///
   /// ```dart
   /// class IncrementIntent extends Intent {
-  ///   const IncrementIntent({this.index});
+  ///   const IncrementIntent({required this.index});
   ///
   ///   final int index;
   /// }
@@ -479,19 +479,19 @@ abstract class ContextAction<T extends Intent> extends Action<T> {
   /// changing the return type of the override to match the type of the returned
   /// value provides more type safety.
   ///
-  /// For instance, if your override of `invoke` returns an `int`, then define
+  /// For instance, if an override of `invoke` returned an `int`, then it might
-  /// it like so:
+  /// be defined like so:
   ///
   /// ```dart
   /// class IncrementIntent extends Intent {
-  ///   const IncrementIntent({this.index});
+  ///   const IncrementIntent({required this.index});
   ///
   ///   final int index;
   /// }
   ///
   /// class MyIncrementAction extends ContextAction<IncrementIntent> {
   ///   @override
-  ///   int invoke(IncrementIntent intent, [BuildContext context]) {
+  ///   int invoke(IncrementIntent intent, [BuildContext? context]) {
   ///     return intent.index + 1;
   ///   }
   /// }

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

@@ -252,11 +252,27 @@ class AnimatedList extends StatefulWidget {
 /// can refer to the [AnimatedList]'s state with a global key:
 ///
 /// ```dart
+/// // (e.g. in a stateful widget)
 /// GlobalKey<AnimatedListState> listKey = GlobalKey<AnimatedListState>();
-/// ...
+///
-/// AnimatedList(key: listKey, ...);
+/// // ...
-/// ...
+///
-/// listKey.currentState.insert(123);
+/// @override
+/// Widget build(BuildContext context) {
+///   return AnimatedList(
+///     key: listKey,
+///     itemBuilder: (BuildContext context, int index, Animation<double> animation) {
+///       return const Placeholder();
+///     },
+///   );
+/// }
+///
+/// // ...
+///
+/// void _updateList() {
+///   // adds "123" to the AnimatedList
+///   listKey.currentState!.insertItem(123);
+/// }
 /// ```
 ///
 /// [AnimatedList] item input handlers can also refer to their [AnimatedListState]
@@ -440,11 +456,27 @@ class SliverAnimatedList extends StatefulWidget {
 /// can refer to the [SliverAnimatedList]'s state with a global key:
 ///
 /// ```dart
-/// GlobalKey<SliverAnimatedListState> listKey = GlobalKey<SliverAnimatedListState>();
+/// // (e.g. in a stateful widget)
-/// ...
+/// GlobalKey<AnimatedListState> listKey = GlobalKey<AnimatedListState>();
-/// SliverAnimatedList(key: listKey, ...);
+///
-/// ...
+/// // ...
-/// listKey.currentState.insert(123);
+///
+/// @override
+/// Widget build(BuildContext context) {
+///   return AnimatedList(
+///     key: listKey,
+///     itemBuilder: (BuildContext context, int index, Animation<double> animation) {
+///       return const Placeholder();
+///     },
+///   );
+/// }
+///
+/// // ...
+///
+/// void _updateList() {
+///   // adds "123" to the AnimatedList
+///   listKey.currentState!.insertItem(123);
+/// }
 /// ```
 ///
 /// [SliverAnimatedList] item input handlers can also refer to their

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

@@ -33,6 +33,9 @@ import 'widget_inspector.dart';
 
 export 'dart:ui' show Locale;
 
+// Examples can assume:
+// late Widget myWidget;
+
 /// The signature of [WidgetsApp.localeListResolutionCallback].
 ///
 /// A [LocaleListResolutionCallback] is responsible for computing the locale of the app's
@@ -947,7 +950,7 @@ class WidgetsApp extends StatefulWidget {
   ///
   /// ```dart
   /// // Full Chinese support for CN, TW, and HK
-  /// supportedLocales: [
+  /// supportedLocales: <Locale>[
   ///   const Locale.fromSubtags(languageCode: 'zh'), // generic Chinese 'zh'
   ///   const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans'), // generic simplified Chinese 'zh_Hans'
   ///   const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant'), // generic traditional Chinese 'zh_Hant'