Proposal: @include, @example directives

[jonasfj]

This issue proposes 3 new dartdoc directives:

• {@include <path-to-file>[#<region>] [<options>]}, include a file region as markdown.
• {@example <path-to-file>[#<region>] [<options>]}, include a file region as fenced code snippet.

, where

• <path-to-file> is one of:
  • relative-path (e.g. ../test/example.dart), relative to the file that the directive appears in.
  • absolute-path (e.g. /src/myfile.dart), relative to the packageUri` of the current package
    • packageUri is lib/ folder in the root of the current package directory.
    • This the same logic as import-statements.
  • package URI (e.g. package:foo/foo.dart), URI relative to lib/ within given package.
• <region> is a region within the file (see Region resolution below), given as fragment in the URI for the file.
• <options> is space separated list of (optional) options:
  • lang=<language>, language marker for the example (only applicable to {@example} directive).
    Default value is inferred from the file extension of <path-to-file>.
  • indent=keep|strip, whether to keep or strip indentation (see Whitespace stripping below)

Use cases:

• Testable code samples in documentation (by embedding regions from a test file)
• Break large code samples into small regions, embed and explain them bit by bit.
• Include a markdown file when writing very large documentation comments, instead of writing hundreds of lines in ///-prefixed doc comments (for better ergonomics).

Region resolution

We should allow authors to not just reference a specific file, but also a region within said file.

This proposal suggests that:

• Region foo is referenced using a URL-fragment, like ../test/example.dart#foo.
• Region foo is defined as:
  • Lines between #region foo and matching #endregion (allowing for nested regions)
  • Omitting lines that include #hide, #region and #endregion

Example: example/hello.dart

/// Copyright 2025 Google LLC.
/// SPDX-License-Identifier: Apache-2.0

// #region main
void main() {
  // #region hello
  print('hello world');
  // #endregion
  exit(0); // force exit! #hide
}
// #endregion

Example: example/hello.dart#hello

The region becomes:

  print('hello world');

Note: lines with #region and #endregion are not included!

Example: example/hello.dart#main

The region becomes:

void main() {
  print('hello world');
}

Note: lines with #hide are not included!

Whitespace stripping

Many examples are likely to appear nested inside main()/group()/test() callbacks in a file like test/example.dart file. Thus, it's often preferable to strip indentation.

Thus, we propose a indent=strip|keep option that defaults to strip!

Stripping indentation simply means:

• For each non-empty line, remove the minimum number of whitespaces that all non-empty lines has.

It's possible that we should do special things for \t, and that we should consider only removing an even number of whitespaces (I don't know anyone who uses indentation 1).

Example use case

With {@example} directive, we'd be able to write documentation like:

/// The following examples show to use [print]:
/// {@example example/hello.dart#hello}
void print(String line) {

And get the following markdown:

The following examples show to use [print]:
```dart
print('hello world');
```

Notice:

• The language marker dart comes from the file extension.
• We default to stripping indentation.

---

Upsides:

• Documentation examples can be included from example/ or test/:
  • Giving users: auto-completion, syntax highlighting and formatting when writing examples.
  • Enabling documentation examples to also run as test (covered by CI).
  • Authors can omit test setup and technicalities using #region/#hide.
• Compared to {@tool} directives, this is fast and can work on pub.dev (without security concerns).
• Inferring language marker from file extension just works for most file types (dart, yaml, etc).
• Stripping indentation is a good default for most use-cases.
• Path resolution is consistent import-statements from Dart!

Downsides:

• We've introduce a new #region/#endregion/#hide syntax! (inspired by #region in C#)
• Stripping indentation can be a bit surprising.
• Using the same path resolution a import-statements makes it a bit difficult to reference things from test/ and example/ folders.

[loic-sharma]

This proposal looks really clean & elegant to me! Some questions and thoughts:

1. Do we need to support paths with spaces like foo bar/buzz.dart? If so, consider adding (optional?) quotes to the syntax. Something like:

   /// {@example "example/hello world.dart#hello"}

2. It's not clear whether referencing things from test/ and example/ is supported. The example use case indicates this is supported, but the downsides indicates it isn't supported:

   Using the same path resolution a import-statements makes it a bit difficult to reference things from test/ and example/ folders.

   Personally, I'd prefer being able to reference things from test/ and example/ over mirroring the same path resolution as import statements.

3. It'd be useful if Dartdoc also supported a similar feature for README files too. The Flutter packages repo has custom tooling to make sure its READMEs' code samples are up-to-date.

   See:

   • https://github.com/search?q=repo%3Aflutter%2Fpackages%20code-excerpt&type=code
   • https://github.com/flutter/packages/blob/e57e7f432edb7a3fc8a0a4678d9ce8cf80ee1682/script/tool/lib/src/readme_check_command.dart#L27

   That's not a blocker for this design, but ideally we design this in such a way that we'd be able to extend this to READMEs too :)

4. I wonder if #hide should be simplified to match exactly // #hide?

   For example, the // force exit #hide example could be turned into two separate lines:

   // force exit! // #hide
   exit(0); // #hide

   Just a thought, I don't feel strongly :)

[jonasfj]

(1) Quotation: I think we should support quotes, but perhaps it's worth looking at all dartdoc-directives and add such support more widely.

(2) We could allow package:mypkg/../test/mypkg_test.dart, but package:mypkg/../ is kind of a hack. One could also make the reasonable argument that we never want to support pointing into other packages. We could support relative paths only, but that's also painful.

(3) When dartdoc renders a README.md we should support it, but I don't think we should build tooling for doing this on github, the community can make their own tooling, it'll have to work differently.

(4) I think matching #hide and #region is better, because not all files use C-style comments. And # // #hide would be really weird in YAML or bash files :D

I don't particularly love the #hide/#region/#endregion syntax, but #-prefix gives it a C-preprocessor vibe. Maybe capitalization could be considered too.

[dkwingsmt]

From my understanding, this issue consists of the following features.

1. Partial snippet, including regions and hiding
2. Include directives
3. A path syntax similar to file importing
4. Unindenting

Here's my thoughts:

Partial snippet: I suggest we do not support partial snippet.

• Partial snippet isn't very useful for dartpads, since a dartpad is supposed to be runnable and therefore should contain a full runnable app.
• Partial snippet syntax isn't very useful for examples either. Since examples are not meant to be runnable, we can make the example contain only one function / class that needs highlighting, and the our unit tests can import this function / class to test.

In summary, the partial snippet feature isn't a must-have. While it can still be a nice-to-have, it comes with a great cost. A lot of features are designed exclusively to help the region syntax: The #hide/region/endregion directives, the # part at the end of the path syntax, and unindenting. Not supporting partial snippet greatly simplifies the design.

Include directives: I can see where it would be useful, although I wouldn't use it when I'm contributing to flutter/flutter. I think the having the doc and the source code close to each other outweighs the benefit of making the source code denser with non-doc lines. Maybe collect more opinions from the community before proceeding with this feature.

Path syntax: I'm not fully convinced of the current design. I see the benefit of sharing the syntax with file importing, but I don't want to make it harder to import in-packge files (files within the same package) with the current repo structure of flutter/flutter. Importing in-packge files is the most common case and should not require hacks like /../.

• That being said, I'm ok with keeping the current design as long as we complement it with a style suggestion on where to place the example files and doc files. This will require Flutter to move the files, but that's ok as a one-time migration as long as it's well defined and agreed within the community.
• I don't think cross-package importing will be very useful.
• I think that absolute paths is much more useful than relative paths, at least with the repo structure of flutter/flutter, where sources files and non-sources files are placed in different root folders. We should prioritize the convenience with absolute paths.

Unindenting: No longer needed if we don't need to support partial snippet.

[jonasfj]

@szakarias and I had an IRL conversation with Lasse and Johnni yesterday, the takeaway was:

• path resolution should be relative to packageRootUri from .dart_tool/package_config.json
  • We should not used the same path resolution as import statements, because:
    • Users will want to reference files from test/ or example/
    • package:my_pkg/../test/... doesn't really work
    • Allowing loading of files from other packages is probably not a good idea.
• The #region/#endregion/#hide syntax could be done in many ways, we should look at what others are already doing:
  • dart-lang/site-www uses #docregion <name> / #enddocregion <name>
  • GCP style guide uses [START <name>] / [END <name>]
  • flutter/packages uses #docregion <name> / #enddocregion <name>

I can totally see that region resolution and indentation stripping complicates things, and aren't perhaps strictly needed now.

But we already see places doing this. I've personally used it extensively in package:typed_sql docs where samples are referenced from files in test/. Granted I'm obviously biased :D

[dcharkes]

I love it, love it, love it!

Here's my poor mans version right now:

• Generator: https://github.com/dart-lang/native/blob/bf77b81e80a33114bb03861893393156e8ff3fbc/pkgs/hooks/tool/update_snippets.dart#L10
• An example snippet: https://github.com/dart-lang/native/blob/bf77b81e80a33114bb03861893393156e8ff3fbc/pkgs/hooks/example/api/config_snippet_3.dart#L7-L32

Using // #<...> as a way to specify regions sgtm. Note that sometimes comments get pushed with an extra newline by the formatter. So make sure to trim() the sample before embedding it.

[lrhn]

We could allow package:mypkg/../test/mypkg_test.dart, but package:mypkg/../ is kind of a hack.

And a bad one that doesn't work with standard tools.
If you parse the former using the Uri class, it becomes package:mypkg/test/mypkg_test.dart.

For quotes ... not really needed if the paths should be URIs. URIs can't contain spaces either, they should be escaped as %20.
Allowing quotes shouldn't hurt, and Uri.parse will quote your spaces for you.

You should not be referring to parts of another package that is not publicly shared, aka. inside lib/.
Anything outside of there may depend on dev-dependencies that are not available or known to the current package.

Anything you do with relative paths need to answer "relative to what?".
If the file is inside lib/, is a relative path relative to its package: URI or its file: URI? Or something else?
(For example, you could make all such relative paths relative to the the file's own position relative to the Pub package root, treating the Pub package root as a path root. Or to the Pub workspace root, if inside a workspace. Then you cant ../ your way out of the package.)

You probably want to be able to use the same relative URIs for doc-imports inside lib/ as you do for actual imports, which is relative to the package: URI, so /src/banana.dart should probably resolve to package:thispackage/src/banana.dart.

That suggests that you need a way to refer to the current Pub package root explicitly, when relative URIs are relative to a package: URI.
Let's strawman it as pub:. Then you can do {@example pub:/docs/examples/example1.dart}, which is an absolute URI relative to the root of the current Pub package, and an error if not inside a Pub package. (Can even allow pub://otherpkg/test/test_test.dart to refer to a file of another package, you just should't be using that for anything.
And then all files outside of / can resolve their relative URIs relative to the pub: path of the containing file, pub://currentPkg/my_path/my_file.dart.

I think we can define this in a reasonable manner, but files inside lib/ should still default to their package: URI for everything. If they do need to refer outside of lib/, they need to do it explicitly, not using a relative path.

[sigurdm]

Linking this to: dart-lang/language#4616 (comment) as a related discussion