Summary - Documentation
- Dart course
- Intermediate
- Lesson 111/116
- 5 min
Combine dartdoc, /// and Markdown to write a documented library.
Summary - Documentation
In this group you learned Dart documentation: dartdoc, /// doc comments, Markdown, [name] references and example code blocks.
Summary: dart doc produces HTML; /// writes a doc comment; Markdown adds rich formatting; [name] links parameters; ```dart shows example code.
Good docs need a short first sentence, correct parameter links and working example code; avoid over-formatting.
A combined example
A doc comment combining everything: under /// Multiplies the base by itself. add /// Returns the square of [base]. and optionally an example block.
Then the function: int power(int base) => base * base;. dartdoc builds a summary, parameter link and example from this comment.
Repeat this pattern for every public API in your package; it gives consistent docs.
Practice A documented function
Write int power(int base) => base * base;. Add a two-line doc comment above it: first line /// Multiplies the base by itself., second line /// Returns the square of [base].. In main call print(power(6)).
Starter code
// Write the power function and its doc comment
void main() {
// print the result of power(6)
}Sample solution
/// Multiplies the base by itself.
/// Returns the square of [base].
int power(int base) => base * base;
void main() {
print(power(6));
}Expected output
36
Questions and answers
Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.
1 How is a parameter reference written in Dart?
- @param name
- [name] Correct answer
- $name
- &name
Explanation: [name] brackets give a parameter link.
2 Documentation summary
| Term | Meaning |
|---|---|
dart doc |
Produces HTML |
/// |
Doc comment |
[name] |
Parameter |
```dart |
Code block |
3 Example code block
/// ____dart/// ```dartExplanation: ```dart opens the code block.