dart-use-doc-examples

Using Examples in Dartdoc

Contents

• 1. The {@example} Directive
• 2. Using Regions
• 3. Hiding Setup Code
• 4. Marker Filtering Rules
• 5. Placement and Path Resolution
• 6. Verification

When writing documentation that requires multi-line code examples, you should generally extract those examples into standalone .dart files and inject them using the {@example} directive, rather than writing them inline inside /// comments. This ensures the examples can be analyzed, linted, and executed.

1. The {@example} Directive

The {@example} directive parses an external file and resolves it into a fenced Markdown code block in the generated documentation.

Syntax: {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}

Using Examples in Dartdoc

Contents

• 1. The {@example} Directive
• 2. Using Regions
• 3. Hiding Setup Code
• 4. Marker Filtering Rules
• 5. Placement and Path Resolution
• 6. Verification

When writing documentation that requires multi-line code examples, you should generally extract those examples into standalone .dart files and inject them using the {@example} directive, rather than writing them inline inside /// comments. This ensures the examples can be analyzed, linted, and executed.

1. The {@example} Directive

The {@example} directive parses an external file and resolves it into a fenced Markdown code block in the generated documentation.

Syntax: {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}