@param and @return
- Dart course
- Intermediate
- Lesson 109/116
- 5 min
Learn @param and @return tags.
[name] instead of @param and @return
In Dart doc comments parameters are referenced with [name] brackets. The @param and @return tags from Java are not used in Dart.
Example: /// The [name] parameter is greeted. The returned value is a message. dartdoc turns [name] into a link to the parameter docs.
The return value is described in plain prose; no separate tag is needed. This gives more natural-sounding docs.
A [name] example
A typical doc comment: under /// [a] and [b] are summed. you add /// The result is an integer.
[a] and [b] link to the function parameters; the reader can click to jump to the definition. The return value is described in the second sentence.
This approach replaces the Java pair @param a ... @return ... with natural language.
Practice A doc comment with [name]
Write int subtract(int a, int b) => a - b;. Add a doc comment above it: /// [b] is subtracted from [a].. In main call print(subtract(10, 4)).
Starter code
// Write the subtract function and its doc comment
void main() {
// print the result of subtract(10, 4)
}Sample solution
/// [b] is subtracted from [a].
int subtract(int a, int b) => a - b;
void main() {
print(subtract(10, 4));
}Expected output
6
Questions and answers
Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.
1 How is a parameter referenced in Dart?
- @param name
- $name
- #{name}
- [name] Correct answer
Explanation: [name] brackets link to the parameter.
2 Parameter reference
| Term | Meaning |
|---|---|
[name] |
Parameter link |
@param |
Java tag |
/// |
Doc comment |
Plain prose |
Return description |
3 The [name] reference
/// ____ and [b] are added./// [a] and [b] are added.Explanation: [a] links to the parameter.