Agent skill · dart-lang
dart-use-doc-examples
How to inject external code examples into Dartdoc using the {@example} directive, and how to filter those files using #hide, #region, and #endregion tags.
What it needs
About 3k tokens when loaded.
What this skill does
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]} <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 /// final client = Client(); /// client.send(); /// Good (External File Injection): 2. Using Regions Often, an external example file contains imports, setup, or void main() wrappers that you don't want to show in the documentation. You can extract a specific block of code by appending #<region> to the {@example} directive path, and wrapping that code with #region and #endregion comments in the target file. Dart Code (e.g., /example/client.dart): Dartdoc Usage: 3. Hiding Setup Code If there is a specific line of code within your extracted region that is necessary for the compiler/analyzer to pass but irrelevant (or distracting) for the documentation reader, append #hide to that line. Dart Code: In the generated documentation, only final data = await fetch(mockServer.url); will be visible. The line with #hide is completely dropped. 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills dart-lang/dart-use-doc-examples