Show/expand Dart templates in source editor

[matthew-carroll]

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.

[rydmike]

Totally agree. I made a related suggestion in Flutter repo here https://github.com/flutter/flutter/issues/77607 since Dart team in the existing related topic in Dart repo here https://github.com/dart-lang/sdk/issues/45234 suggested to add it there.

Expanding the macros, with an extra tooling pass would be more universal, enabling reading the comments in GitHub repos too. But above support in IDEs would be very welcome too.

[timsneath]

Thanks. I believe this is not unique to IntelliJ. I assume it's coming from the analyzer? @kevmoo might be interested in this, as he's tracking doc frictions at the moment.

[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.

[kevmoo]

I love this idea. I've worked out a number of (suggested) improvements for the consumption experience for docs. I agree there's a lot we could do on the authoring side, too! (Like having consistent doc comment parsing between the analyzer and dartdoc)

[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.