Flutter 和 Dart 文档中的@macro 注释是什么

Question

When I'm reading the source code I often see something like this (from TextField ):

/// {@macro flutter.widgets.editableText.keyboardType}
final TextInputType keyboardType;

What does the @macro mean?

I found the answer so I'm posting it below as a self-answer Q&A.

Answer 1

A @macro is a way to insert some dartdoc documentation that has been written somewhere else. That way you don't have duplicate docs that you have to maintain.

The string that follows @macro is the name of a template, which includes the documentation you'll insert. So in the TextField example:

/// {@macro flutter.widgets.editableText.keyboardType}
final TextInputType keyboardType;

the template name is flutter.widgets.editableText.keyboardType . If you go to the source code for EditableText , you'll find the template with it's documentation text:

/// {@template flutter.widgets.editableText.keyboardType}
/// The type of keyboard to use for editing the text.
///
/// Defaults to [TextInputType.text] if [maxLines] is one and
/// [TextInputType.multiline] otherwise.
/// {@endtemplate}
final TextInputType keyboardType;

The annotation @template starts the template and is followed by its name. @endtemplate finishes it.

When you view the documentation for EditableText.keyboardType and TextField.keyboardType , you can see they are exactly the same:

• https://api.flutter.dev/flutter/widgets/EditableText/keyboardType.html
• https://api.flutter.dev/flutter/material/TextField/keyboardType.html

Read more in the dartdoc documentation .