dart-use-doc-exampleslisted

# Using Examples in Dartdoc ## Contents * [1. The `{@example}` Directive](#1-the-example-directive) * [2. Using Regions](#2-using-regions) * [3. Hiding Setup Code](#3-hiding-setup-code) * [4. Marker Filtering Rules](#4-marker-filtering-rules) * [5. Placement and Path Resolution](#5-placement-and-path-resolution) * [6. Verification](#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]}` * **`<path>`**: The path to the file. A leading `/` evaluates from the package root. Otherwise, it is relative to the current file. * **`lang`**: The language for the markdown fence. Auto-detected from the file extension (e.g., `dart`), but can be explicit (e.g., `lang=text`). * **`indent`**: `strip` (default) aggressively removes shared leading indentation from the code block. *Bad (Inline Markdown):* ```dart /// Makes a client service request to the backend. /// /// ```dart /// final client = Client(); /// client.send(); /// ``` ``` *Good (External File Inject