What is the @macro annotation in Flutter and Dart documentation
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.
Comments
-
Suragch over 1 year
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.
-
Adnan almost 3 yearsI've searched for something like this recently but now I found it by coincidence. is there some documentation about all of this magic stuff?
-
Suragch almost 3 years@Adnan, there is a bit in that last link I included.