CodeBlanks Logo Icon CodeBlanks
Login Register

dartdoc

Learn documentation generation with dartdoc.

dartdoc

dartdoc is Dart's official documentation generator. It reads the doc comments (///) in your source code and produces HTML documentation.

Command: dart doc (new name) or dartdoc (legacy). Output is written to the doc/api/ folder by default.

Writing a doc comment for every public API in a package is good practice; dartdoc gathers them automatically.

The dart doc command

The dart doc command scans the files under lib/, gathers the /// comments and produces HTML in the doc/api/ folder.

You can change the output location with --output: dart doc --output build/docs. This gives output suited to build systems.

Open the generated HTML in a browser to browse your package's API docs.

Practice A doc comment for dartdoc

Write String greet(String name) => 'Hello $name';. Add a doc comment above it: /// Greets the name.. In main print print(greet('Alex')).

Starter code

main.dart
// Write the greet function and its doc comment

void main() {
  // print the greet('Alex') call
}

Sample solution

main.dart
/// Greets the name.
String greet(String name) => 'Hello $name';

void main() {
  print(greet('Alex'));
}

Expected output

Hello Alex

Questions and answers

Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.

1 What does dartdoc produce?

  • HTML documentation Correct answer
  • Runnable code
  • Test report
  • Package file

Explanation: dartdoc builds HTML pages from doc comments.

2 The dart doc command

Question 
dart ____ --output build/docs
Answer 
dart doc --output build/docs

Explanation: dart doc generates documentation.

3 dartdoc parts

Term Meaning
dart doc Command
/// Doc comment
lib/ Scanned folder
HTML Output format

All lessons in Intermediate

1 Classes in depth

  1. Constructor types
  2. Named constructors
  3. Initializer list
  4. const constructor
  5. factory
  6. Summary - Classes

2 Inheritance

  1. extends
  2. super
  3. Override
  4. abstract
  5. interface
  6. Summary - Inheritance

3 Project: Helper library

  1. Module design
  2. String helpers
  3. Number helpers
  4. Date helpers
  5. Putting it together

4 Encapsulation

  1. private
  2. Getters and setters
  3. final and const fields
  4. late
  5. static
  6. Summary - Encapsulation

5 Mixins

  1. mixin
  2. Using mixins
  3. mixin constraints
  4. Multiple mixins
  5. mixin vs inheritance
  6. Summary - Mixins

6 Generics

  1. Generic class
  2. Generic methods
  3. Type constraints
  4. Generic collections
  5. Generics vs dynamic
  6. Summary - Generics

7 Project: Quiz app

  1. Quiz model
  2. Adding questions
  3. Running the quiz
  4. Score calculation
  5. Putting it together

8 Collections

  1. List
  2. Set
  3. Map
  4. Queue
  5. Iterable
  6. Summary - Collections

9 Collection methods

  1. map
  2. where
  3. fold and reduce
  4. forEach
  5. any and every
  6. Summary - Collection methods

10 Project: Library app

  1. Model design
  2. Library class
  3. Checking out
  4. Search and filter
  5. Putting it together

11 Async in depth

  1. Future
  2. async/await
  3. Future chaining
  4. Future.wait
  5. Completer
  6. Summary - Async

12 Streams

  1. What are streams?
  2. Listening to streams
  3. Stream transformation
  4. asyncExpand
  5. StreamController
  6. Summary - Streams

13 Type aliases

  1. typedef
  2. Type alias
  3. Record
  4. Pattern matching
  5. switch expression
  6. Summary - Type aliases

14 Metadata and annotations

  1. Metadata
  2. Custom annotations
  3. @override
  4. @deprecated
  5. Reflection
  6. Summary - Metadata

15 Testing

  1. dart test
  2. test and expect
  3. group
  4. setUp and tearDown
  5. Mock
  6. Summary - Testing

16 File I/O

  1. dart:io
  2. File.readAsString
  3. File.writeAsString
  4. exists
  5. Directory
  6. Summary - File I/O

17 Packages

  1. pub
  2. pubspec.yaml
  3. pub get
  4. import
  5. pub publish
  6. Summary - Packages

18 Advanced error handling

  1. Exception hierarchy
  2. Error vs Exception
  3. Stack trace
  4. Result pattern
  5. Async errors
  6. Summary - Advanced error handling

19 Documentation

  1. dartdoc
  2. Doc comments
  3. Markdown
  4. @param and @return
  5. Example code
  6. Summary - Documentation

20 Intermediate final

  1. Project design
  2. OOP model
  3. Collections
  4. File I/O
  5. Putting it together