Standardize macro names for dartdoc macros (#22180)

lib/ui/painting.dart

@@ -19,6 +19,15 @@ part of dart.ui;
 // which can not be rendered by Skia.
 
 // Update this list when changing the list of supported codecs.
+/// {@template dart.ui.imageFormats}
+/// JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, and WBMP. Additional
+/// formats may be supported by the underlying platform. Flutter will
+/// attempt to call platform API to decode unrecognized formats, and if the
+/// platform API supports decoding the image Flutter will be able to render it.
+/// {@endtemplate}
+
+// TODO(gspencergoog): remove this template block once the framework templates
+// are renamed to not reference it.
 /// {@template flutter.dart:ui.imageFormats}
 /// JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, and WBMP. Additional
 /// formats may be supported by the underlying platform. Flutter will
@@ -1960,7 +1969,7 @@ class Codec extends NativeFieldWrapperClass2 {
 ///
 /// The `list` parameter is the binary image data (e.g a PNG or GIF binary data).
 /// The data can be for either static or animated images. The following image
-/// formats are supported: {@macro flutter.dart:ui.imageFormats}
+/// formats are supported: {@macro dart.ui.imageFormats}
 ///
 /// The `targetWidth` and `targetHeight` arguments specify the size of the
 /// output image, in image pixels. If they are not equal to the intrinsic

lib/ui/platform_dispatcher.dart

@@ -209,7 +209,6 @@ class PlatformDispatcher {
 
   /// A callback invoked when any view begins a frame.
   ///
-  /// {@template flutter.foundation.PlatformDispatcher.onBeginFrame}
   /// A callback that is invoked to notify the application that it is an
   /// appropriate time to provide a scene using the [SceneBuilder] API and the
   /// [FlutterView.render] method.
@@ -218,7 +217,6 @@ class PlatformDispatcher {
   /// screen with the highest VSync rate. This is only called if
   /// [PlatformDispatcher.scheduleFrame] has been called since the last time
   /// this callback was invoked.
-  /// {@endtemplate}
   FrameCallback? get onBeginFrame => _onBeginFrame;
   FrameCallback? _onBeginFrame;
   Zone _onBeginFrameZone = Zone.root;
@@ -236,13 +234,11 @@ class PlatformDispatcher {
     );
   }
 
-  /// {@template flutter.foundation.PlatformDispatcher.onDrawFrame}
   /// A callback that is invoked for each frame after [onBeginFrame] has
   /// completed and after the microtask queue has been drained.
   ///
   /// This can be used to implement a second phase of frame rendering that
   /// happens after any deferred work queued by the [onBeginFrame] phase.
-  /// {@endtemplate}
   VoidCallback? get onDrawFrame => _onDrawFrame;
   VoidCallback? _onDrawFrame;
   Zone _onDrawFrameZone = Zone.root;

lib/ui/text.dart

@@ -432,7 +432,7 @@ enum TextDecorationStyle {
   wavy
 }
 
-/// {@template flutter.dart:ui.textHeightBehavior}
+/// {@template dart.ui.textHeightBehavior}
 /// Defines how the paragraph will apply [TextStyle.height] to the ascent of the
 /// first line and descent of the last line.
 ///
@@ -1638,7 +1638,7 @@ enum BoxHeightStyle {
   /// The top and bottom of each box will cover half of the
   /// space above and half of the space below the line.
   ///
-  /// {@template flutter.dart:ui.boxHeightStyle.includeLineSpacing}
+  /// {@template dart.ui.boxHeightStyle.includeLineSpacing}
   /// The top edge of each line should be the same as the bottom edge
   /// of the line above. There should be no gaps in vertical coverage given any
   /// amount of line spacing. Line spacing is not included above the first line
@@ -1650,14 +1650,14 @@ enum BoxHeightStyle {
   ///
   /// The line spacing will be added to the top of the box.
   ///
-  /// {@macro flutter.dart:ui.boxHeightStyle.includeLineSpacing}
+  /// {@macro dart.ui.boxHeightStyle.includeLineSpacing}
   includeLineSpacingTop,
 
   /// Extends the bottom edge of the bounds to fully cover any line spacing.
   ///
   /// The line spacing will be added to the bottom of the box.
   ///
-  /// {@macro flutter.dart:ui.boxHeightStyle.includeLineSpacing}
+  /// {@macro dart.ui.boxHeightStyle.includeLineSpacing}
   includeLineSpacingBottom,
 
   /// Calculate box heights based on the metrics of this paragraph's [StrutStyle].
@@ -2280,4 +2280,16 @@ FutureOr<void> _sendFontChangeMessage() async {
   );
 }
 
+// TODO(gspencergoog): remove this template block once the framework templates
+// are renamed to not reference it.
+/// {@template flutter.dart:ui.textHeightBehavior}
+/// Defines how the paragraph will apply [TextStyle.height] to the ascent of the
+/// first line and descent of the last line.
+///
+/// Each boolean value represents whether the [TextStyle.height] modifier will
+/// be applied to the corresponding metric. By default, all properties are true,
+/// and [TextStyle.height] is applied as normal. When set to false, the font's
+/// default ascent will be used.
+/// {@endtemplate}
+
 String _loadFontFromList(Uint8List list, _Callback<void> callback, String? fontFamily) native 'loadFontFromList';

lib/ui/window.dart

@@ -312,7 +312,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// [physicalSize], [padding], [viewInsets], [PlatformDispatcher.views], or
   /// [systemGestureInsets] values change.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// See [PlatformDispatcher.onMetricsChanged] for more information.
   VoidCallback? get onMetricsChanged => platformDispatcher.onMetricsChanged;
@@ -322,7 +322,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// The system-reported default locale of the device.
   ///
-  /// {@template flutter.lib.ui.window.accessorForwardWarning}
+  /// {@template dart.ui.window.accessorForwardWarning}
   /// Accessing this value returns the value contained in the
   /// [PlatformDispatcher] singleton, so instead of getting it from here, you
   /// should consider getting it from `WidgetsBinding.instance.platformDispatcher` instead
@@ -344,7 +344,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// The full system-reported supported locales of the device.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This establishes the language and formatting conventions that window
   /// should, if possible, use to render their user interface.
@@ -374,7 +374,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// A callback that is invoked whenever [locale] changes value.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -390,7 +390,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// The lifecycle state immediately after dart isolate initialization.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This property will not be updated as the lifecycle changes.
   ///
@@ -400,7 +400,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// The system-reported text scale.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This establishes the text scaling factor to use when rendering text,
   /// according to the user's platform preferences.
@@ -417,14 +417,14 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// The setting indicating whether time should always be shown in the 24-hour
   /// format.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This option is used by [showTimePicker].
   bool get alwaysUse24HourFormat => platformDispatcher.alwaysUse24HourFormat;
 
   /// A callback that is invoked whenever [textScaleFactor] changes value.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -440,7 +440,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// The setting indicating the current brightness mode of the host platform.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// If the platform has no preference, [platformBrightness] defaults to
   /// [Brightness.light].
@@ -448,7 +448,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// A callback that is invoked whenever [platformBrightness] changes value.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -466,7 +466,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// time to provide a scene using the [SceneBuilder] API and the [render]
   /// method.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// When possible, this is driven by the hardware VSync signal. This is only
   /// called if [scheduleFrame] has been called since the last time this
@@ -493,7 +493,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// A callback that is invoked for each frame after [onBeginFrame] has
   /// completed and after the microtask queue has been drained.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This can be used to implement a second phase of frame rendering that
   /// happens after any deferred work queued by the [onBeginFrame] phase.
@@ -515,7 +515,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// A callback that is invoked to report the [FrameTiming] of recently
   /// rasterized frames.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// It's prefered to use [SchedulerBinding.addTimingsCallback] than to use
   /// [SingletonFlutterWindow.onReportTimings] directly because
@@ -542,7 +542,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// A callback that is invoked when pointer data is available.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -559,7 +559,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// The route or path that the embedder requested when the application was
   /// launched.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This will be the string "`/`" if no particular route was requested.
   ///
@@ -589,7 +589,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// Requests that, at the next appropriate opportunity, the [onBeginFrame] and
   /// [onDrawFrame] callbacks be invoked.
   ///
-  /// {@template flutter.lib.ui.window.functionForwardWarning}
+  /// {@template dart.ui.window.functionForwardWarning}
   /// Calling this function forwards the call to the same function on the
   /// [PlatformDispatcher] singleton, so instead of calling it here, you should
   /// consider calling it on `WidgetsBinding.instance.platformDispatcher` instead (or, when
@@ -607,7 +607,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// Whether the user has requested that [updateSemantics] be called when
   /// the semantic contents of window changes.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The [onSemanticsEnabledChanged] callback is called whenever this value
   /// changes.
@@ -615,7 +615,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// A callback that is invoked when the value of [semanticsEnabled] changes.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -627,7 +627,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// A callback that is invoked whenever the user requests an action to be
   /// performed.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// This callback is used when the user expresses the action they wish to
   /// perform based on the semantics supplied by [updateSemantics].
@@ -644,7 +644,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// A callback that is invoked when the value of [accessibilityFeatures] changes.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The framework invokes this callback in the same zone in which the
   /// callback was set.
@@ -655,7 +655,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// Change the retained semantics data about this window.
   ///
-  /// {@macro flutter.lib.ui.window.functionForwardWarning}
+  /// {@macro dart.ui.window.functionForwardWarning}
   ///
   /// If [semanticsEnabled] is true, the user has requested that this function
   /// be called whenever the semantic content of this window changes.
@@ -666,7 +666,7 @@ class SingletonFlutterWindow extends FlutterWindow {
 
   /// Sends a message to a platform-specific plugin.
   ///
-  /// {@macro flutter.lib.ui.window.functionForwardWarning}
+  /// {@macro dart.ui.window.functionForwardWarning}
   ///
   /// The `name` parameter determines which plugin receives the message. The
   /// `data` parameter contains the message payload and is typically UTF-8
@@ -684,7 +684,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// Called whenever this window receives a message from a platform-specific
   /// plugin.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// The `name` parameter determines which plugin sent the message. The `data`
   /// parameter is the payload and is typically UTF-8 encoded JSON but can be
@@ -704,7 +704,7 @@ class SingletonFlutterWindow extends FlutterWindow {
   /// Set the debug name associated with this platform dispatcher's root
   /// isolate.
   ///
-  /// {@macro flutter.lib.ui.window.accessorForwardWarning}
+  /// {@macro dart.ui.window.accessorForwardWarning}
   ///
   /// Normally debug names are automatically generated from the Dart port, entry
   /// point, and source file. For example: `main.dart$main-1234`.

lib/web_ui/lib/src/engine/platform_dispatcher.dart

@@ -101,7 +101,6 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
 
   /// A callback invoked when any window begins a frame.
   ///
-  /// {@template flutter.foundation.PlatformDispatcher.onBeginFrame}
   /// A callback that is invoked to notify the application that it is an
   /// appropriate time to provide a scene using the [SceneBuilder] API and the
   /// [PlatformWindow.render] method.
@@ -109,7 +108,6 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
   /// screen with the highest VSync rate. This is only called if
   /// [PlatformWindow.scheduleFrame] has been called since the last time this
   /// callback was invoked.
-  /// {@endtemplate}
   @override
   ui.FrameCallback? get onBeginFrame => _onBeginFrame;
   ui.FrameCallback? _onBeginFrame;
@@ -126,13 +124,11 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
     _invoke1<Duration>(_onBeginFrame, _onBeginFrameZone, duration);
   }
 
-  /// {@template flutter.foundation.PlatformDispatcher.onDrawFrame}
   /// A callback that is invoked for each frame after [onBeginFrame] has
   /// completed and after the microtask queue has been drained.
   ///
   /// This can be used to implement a second phase of frame rendering that
   /// happens after any deferred work queued by the [onBeginFrame] phase.
-  /// {@endtemplate}
   @override
   ui.VoidCallback? get onDrawFrame => _onDrawFrame;
   ui.VoidCallback? _onDrawFrame;