Make it an error to break macros in docs (and fix existing broken macros) (#62071)

dartdoc_options.yaml

@@ -12,3 +12,10 @@ dartdoc:
     dartpad:
       command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"]
       description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
+  errors:
+    - tool-error  # enabled by default
+    - duplicate-file  # enabled by default
+    - invalid-parameter  # enabled by default
+    - unresolved-export  # enabled by default
+    - unknown-macro  # a {@macro foo} reference cannot be resolved
+    - invalid-parameter  # an invalid parameter is passed to a {@foo x y} directive

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

@@ -119,7 +119,7 @@ class RawMaterialButton extends StatefulWidget {
   ///  * [MaterialState.disabled].
   ///
   /// If this property is null, [MaterialStateMouseCursor.clickable] will be used.
-  /// {@endtemplate flutter.material.button.mouseCursor}
+  /// {@endtemplate}
   final MouseCursor mouseCursor;
 
   /// Defines the default text style, with [Material.textStyle], for the

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

@@ -245,7 +245,7 @@ class ColorScheme with Diagnosticable {
 
   /// Linearly interpolate between two [ColorScheme] objects.
   ///
-  /// {@macro flutter.material.themeData.lerp}
+  /// {@macro dart.ui.shadow.lerp}
   static ColorScheme lerp(ColorScheme a, ColorScheme b, double t) {
     return ColorScheme(
       primary: Color.lerp(a.primary, b.primary, t),

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

@@ -278,7 +278,7 @@ class IconButton extends StatelessWidget {
   /// If this is set to null, the button will be disabled.
   final VoidCallback onPressed;
 
-  /// {@macro flutter.material.inkwell.mousecursor}
+  /// {@macro flutter.material.button.mouseCursor}
   ///
   /// Defaults to [SystemMouseCursors.click].
   final MouseCursor mouseCursor;

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

@@ -126,7 +126,7 @@ class ScaffoldPrelayoutGeometry {
   /// The minimum padding to inset the [FloatingActionButton] by for it
   /// to remain visible.
   ///
-  /// This value is the result of calling [MediaQuery.padding] in the
+  /// This value is the result of calling [MediaQueryData.padding] in the
   /// [Scaffold]'s [BuildContext],
   /// and is useful for insetting the [FloatingActionButton] to avoid features like
   /// the system status bar or the keyboard.

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

@@ -685,7 +685,7 @@ class TextTheme with Diagnosticable {
 
   /// Linearly interpolate between two text themes.
   ///
-  /// {@macro flutter.material.themeData.lerp}
+  /// {@macro dart.ui.shadow.lerp}
   static TextTheme lerp(TextTheme a, TextTheme b, double t) {
     assert(t != null);
     return TextTheme(

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

@@ -330,7 +330,7 @@ class RenderEditable extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
     markNeedsTextLayout();
   }
 
-  /// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
+  /// {@macro flutter.painting.textPainter.textWidthBasis}
   TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
   set textWidthBasis(TextWidthBasis value) {
     assert(value != null);

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

@@ -269,7 +269,7 @@ class RenderParagraph extends RenderBox
     markNeedsLayout();
   }
 
-  /// {@macro flutter.widgets.basic.TextWidthBasis}
+  /// {@macro flutter.painting.textPainter.textWidthBasis}
   TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
   set textWidthBasis(TextWidthBasis value) {
     assert(value != null);

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

@@ -210,7 +210,11 @@ class RawKeyEventDataWindows extends RawKeyEventData {
   /// This mask is used to check the [modifiers] field to test whether one of the
   /// SHIFT modifier keys is pressed.
   ///
-  /// {@macro flutter.services.rawKeyEventDataWindows.modifiers}
+  /// {@template flutter.services.rawKeyEventDataWindows.modifiers}
+  /// Use this value if you need to decode the [modifiers] field yourself, but
+  /// it's much easier to use [isModifierPressed] if you just want to know if
+  /// a modifier is pressed.
+  /// {@endtemplate}
   static const int modifierShift = 1 << 0;
 
   /// This mask is used to check the [modifiers] field to test whether the left

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

@@ -5271,7 +5271,7 @@ class RichText extends MultiChildRenderObjectWidget {
   /// {@macro flutter.painting.textPainter.strutStyle}
   final StrutStyle strutStyle;
 
-  /// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
+  /// {@macro flutter.painting.textPainter.textWidthBasis}
   final TextWidthBasis textWidthBasis;
 
   /// {@macro flutter.dart:ui.textHeightBehavior}

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

@@ -695,7 +695,7 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
   /// A future that completes when the Flutter engine has rasterized the first
   /// frame.
   ///
-  /// {@macro flutter.frame_rasterize_vs_presented}
+  /// {@macro flutter.frame_rasterized_vs_presented}
   ///
   /// See also:
   ///

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

@@ -518,7 +518,7 @@ class EditableText extends StatefulWidget {
   /// {@macro flutter.dart:ui.textHeightBehavior},
   final TextHeightBehavior textHeightBehavior;
 
-  /// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
+  /// {@macro flutter.painting.textPainter.textWidthBasis}
   final TextWidthBasis textWidthBasis;
 
   /// {@template flutter.widgets.editableText.readOnly}
@@ -685,6 +685,7 @@ class EditableText extends StatefulWidget {
   /// See [RenderEditable.locale] for more information.
   final Locale locale;
 
+  /// {@template flutter.widgets.editableText.textScaleFactor}
   /// The number of font pixels for each logical pixel.
   ///
   /// For example, if the text scale factor is 1.5, text will be 50% larger than
@@ -692,6 +693,7 @@ class EditableText extends StatefulWidget {
   ///
   /// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
   /// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
+  /// {@endtemplate}
   final double textScaleFactor;
 
   /// The color to use when painting the cursor.