Show/expand Dart templates in source editor

Dart supports documentation templates, for example:

/// This is the dart doc for some property.
///
/// {@template some_template}
/// This explanation is needed many places in our docs, so we wrap it with a
/// template.
/// {@endtemplate}

/// This is another doc for some other property, which replicates our templated
/// doc.
///
/// {@macro some_template}

This templating behavior is critical to keep related documentation in sync. However, these templates are a significant nuisance for developers who are working in source code.

I routinely jump into Flutter source to read docs, only to find a @macro where I was expecting documentation. I have the same problem in my own source code where macros are used.

I’d like to see one or both of the following in the IDE:

• Source linking for template macro’s so that I can CMD+B to the definition of the template.
• Automatic IDE expansion of a macro template so that I can read a template inline, as if it were written in the source code docs that I’m reading.

[DanTup]

@DanTup is this something that could be added to VS Code? I saw that LSP had the basic protocol, but I doubt the analyzer handles @marco there, either.

The analyzer does already do some substitution of @macro/@template, but I think it only happens in a few places like hovers (although I think in LSP we use that hover code in a few additional places like Code Completion to get the same results). I did start looking at making Go-to-Definition work on it a while back, but there was something complicated that made me park it - perhaps I should look again and remind myself what it was.

Although we can’t replace any text in the source file in VS Code, we could potentially inject the target text using decorations (similar to how we inject the “closing labels”), although I’m not sure we if could make it expandable/collapsable so I’m not sure exactly how it would look without doing some experimenting.

[stevemessick]

There are a number of requests (or interpretations) similar to this. For clarity:

• Make the IDE go-to-declaration handle @macro
• Add hover-text expansion of @macro to IDEs
• Change the Flutter SDK to automatically expand @macro in the distributed sources

Changes to the Flutter SDK are covered in https://github.com/flutter/flutter/issues/77607, and that might be the simplest solution (although I’m not too familiar with Flutter distributions).

The first two possibilities are implemented in the Dart plugin. It uses its own index to find declarations, so go-to-declaration changes would have to be implemented there. That would require the Dart parser to recognize @macro and add @template and @macro to the index.

If the analysis server supported @macro then we could, in theory, add support in the Flutter plugin. But the analyzer doesn’t currently recognize @macro AFAIK. @bwilkerson might know more.

@DanTup is this something that could be added to VS Code? I saw that LSP had the basic protocol, but I doubt the analyzer handles @marco there, either.