dart-use-doc-examples

SKILL.md

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]}