How do I create DartDoc Macros/Templates in Dart and Flutter?

Question

I have seen snippets like the following throughout the Flutter repo:

/// {@macro flutter.widgets.editableText.readOnly}

In the IDE and in the rendered Dart docs, it is then shown like this:

Whether the text can be changed.

When this is set to true, the text cannot be modified by any shortcut or keyboard operation. The text is still selectable.

Defaults to false. Must not be null.

And it tends to go way beyond this basic case.

Answer 1

You can create templates and use them as macros using dartdoc, which is the default API documentation package that comes with Flutter.

Simply define an @template anywhere in your docs:

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

Now, you can reuse it anywhere else:

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

Learn more.