Documenting With dartdoc Comments
Write docs that render on pub.dev.
Documenting With dartdoc Comments is a free Dart Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Dart Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Docs Are Part of the Product
Great packages ship great docs. Dart turns special comments into a browsable reference, so documentation is a first-class feature, not an afterthought. 📝
Triple-Slash Doc Comments
A documentation comment starts with three slashes. These doc comments sit right above a declaration and describe what it does for your users.
/// Adds two numbers and returns the sum.
int add(int a, int b) => a + b;Lead With a Single Summary Line
Begin every doc comment with one short summary sentence. Tools show this first line in lists, so make it clear and complete on its own.
Markdown Is Supported
Doc comments accept Markdown, so you can add emphasis, lists, and links. Your rendered page on pub.dev looks polished with almost no effort.
/// Returns the **first** matching item.Link to Other Symbols
Wrap a name in square brackets to create a live cross-link. Readers jump straight to related classes or methods in your generated docs.
/// See [add] for the inverse of [subtract].Code Samples in Fenced Blocks
Show real usage inside a fenced code block in your comment. A short example teaches faster than paragraphs and reassures users it works.
Document Every Public Member
Aim to document each public class, function, and field. Private underscore members can stay quiet, but anything exported deserves a sentence.
Library-Level Docs
Put a doc comment above a library directive to describe the whole file. This library comment becomes the landing text for that part of your API.
/// Math helpers for everyday use.
library calc;Generate the Site With dartdoc
Run the dartdoc tool to turn your comments into a static website. pub.dev runs it for you automatically when you publish.
dart doc .Doc Coverage Earns Points
pub.dev rewards well-documented packages. Higher doc coverage lifts your score and signals quality to anyone choosing a dependency. ⭐
Keep Docs Close to Code
Because doc comments live beside the code, they are easy to update together. Treat stale docs like a bug and fix them when behavior changes.
Quick Check
Which comment style does Dart treat as a documentation comment?
Recap: Docs That Render
You can now write triple-slash doc comments, link symbols, add examples, and generate a site with dart doc. Clear docs win users. 🙌
Frequently asked questions
Is the “Documenting With dartdoc Comments” lesson free?
Yes — the full text of “Documenting With dartdoc Comments” is free to read here on the web, and the Dart Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Dart Academy course, upgrade to CoddyKit PRO.
What will I learn in “Documenting With dartdoc Comments”?
Write docs that render on pub.dev. You practise Dart Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Dart Academy?
No prior experience is required. Dart Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Documenting With dartdoc Comments” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Dart Academy lesson?
Yes. Every Dart Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Structuring a Publishable Library
- Documenting With dartdoc Comments
- Linting, Formatting, and pana Score
- dart pub publish to pub.dev