Dart @macro in comments

Question

What is @macro in dart comments? like

  /// The application's top-level routing table.
  ///
  /// When a named route is pushed with [Navigator.pushNamed], the route name is
  /// looked up in this map. If the name is present, the associated
  /// [WidgetBuilder] is used to construct a [MaterialPageRoute] that performs
  /// an appropriate transition, including [Hero] animations, to the new route.
  ///
  /// {@macro flutter.widgets.widgetsApp.routes}
  final Map<String, WidgetBuilder> routes;

score 12 · Accepted Answer · answered Nov 04 '20 at 07:10

It's part of dartdoc

https://pub.dev/packages/dartdoc#macros

Macros

You can specify "macros", i.e. reusable pieces of documentation. For that, first specify a template anywhere in the comments, like:

/// {@template template_name}
/// Some shared docs
/// {@endtemplate}

and then you can insert it via {@macro template_name}, like

/// Some comment
/// {@macro template_name}
/// More comments

Template definitions are currently unscoped -- if dartdoc reads a file containing a template, it can be used in anything dartdoc is currently documenting. This can lead to inconsistent behavior between runs on different packages, especially if different command lines are used for dartdoc. It is recommended to use collision-resistant naming for any macros by including the package name and/or library it is defined in within the name.

Dart @macro in comments

1 Answers1

Macros