Implement Flutter's `@tool snippet` natively

[srawlins]

I believe the full feature set of Flutter's @tool snippet is as follows: Given text like this:

/// {@tool snippet}
///
/// The following is a skeleton of a stateless widget subclass called `GreenFrog`.
///
/// Normally, widgets have more constructor arguments, each of which corresponds
/// to a `final` property.
///
/// ```dart
/// class GreenFrog extends StatelessWidget {
///   const GreenFrog({ super.key });
///
///   @override
///   Widget build(BuildContext context) {
///     return Container(color: const Color(0xFF2DBD3A));
///   }
/// }
/// ```
/// {@end-tool}

The tool outputs:

1. an invisible anchor, uniquely named
2. the Markdown text above the code block,
3. a link in the top for the invisible anchor,
4. a "copyable" container, with
   1. a copy-to-clipboard button, and
   2. the code snippet in a preformatted tag,
5. all of the contents in a styled snippet-container

All of this sounds perfectly reasonable to bring in-house. We could even stick to the current format of:

/// {@directive-name ...}
/// Text.
///
/// ```dart
/// code;
/// ```
/// {@end-directive-name}

I'm thinking the following features:

• directive can be named @snippet
• directive can take an optional name which will be used for the anchor.
• same output

Though this seems to be even more general purpose than snippets. If we're just talking about a way to:

• style a section in a container,
• include a self-anchor-link,
• add a copy-to-clipboard button,

then we could just call this {@section or something. This might map nicely to an HTML5 tag. This directive would get you the self-link, the custom name for the anchor, maybe the CSS class for styling (so you could do {@section warning} which is highlighted red, and {@section note} which is highlighted blue or whatever.

Then we can add the simple feature where all code blocks have a copy-to-clipboard button. We can maybe recognize no-copy in the info string (```dart no-copy) to omit the copy-to-clipboard button.

WDYT @goderbauer @gspencergoog

[goderbauer]

I like the idea of generalizing it to @section or similar. Could then be used to also highlight other things in docs. Would there be a good way to guard against typos in the CSS class name given? If we define CSS for @section snippet, ideally it should give an indication that @section sippppet is nothing valid.

[srawlins]

Would there be a good way to guard against typos in the CSS class name given?

I can think of a few options:

1. No guard; not to suggest that I like this option, but given priorities, it's a possibility. I think this feature would still not be a step backwards for flutter; @tool snipppet has no protection today, right? So there's that.
2. We can bake into dartdoc a few basic styles, maybe there are similar info-boxes from the Flutter or Dart sites, like note, info, warning, hint; I dunno. So then snippet could be a built-in style.
3. The list of these can be required to be found in dartdoc_options.yaml. I think this is how we guard @category against typos.
4. If we do not write a guard into dartdoc, but the analyzer team ships a nice lightweight plugins feature, this could be guarded, even in the IDE, with an analyzer plugin custom for the Flutter team.

[goderbauer]

The list of these can be required to be found in dartdoc_options.yaml. I think this is how we guard @category against typos.

This would be my preferred option.

[ljmatan]

Hopefully this will come in my lifetime. Good luck!

[ljmatan]

On that note, I've managed to run the snippet tool as such:

export FLUTTER_LIBRARY="some_library" dart run ./packages/snippets/bin.dart --output-directory=./docs/snippets_out/ --type=snippet --input=some_dart_file.dart

This indeed generates the snippet HTML code and the related .json file, however, I'm not sure where to go further in terms of embedding this into the finished HTML pages.

I'm having 2 issues:

1. When I run dart doc ., having added the snippets tool to the dartdoc_options.yaml file, no snippets are generated. It seems that this tool is not invoked at all.
2. When I run dart run dartdoc --apply-tools ..., the Flutter SDK snippets start being generated in the snippets folder which is not even specified in the dartdoc_options.yaml file.

All in all, I haven't had much luck with it :)