Flutter-intellij: Support for DartDoc macros

[goderbauer]

When jumping to the definition of a function or property within the flutter framework I often see something like the following:

  /// {@macro flutter.widgets.widgetsApp.color}
  final Color color;

  /// {@macro flutter.widgets.widgetsApp.locale}
  final Locale locale;

It would be great if IntelliJ would offer some sort of support for these DartDoc macros. I'd love it if IntelliJ would just show inline what the macro is referencing. Or at least provide a link to the referenced location.

[pq]

/cc @jcollins-g @scheglov

[scheglov]

When you say "show inline", do you mean Quick Documentation feature of IntelliJ?

This should be easy to do, although very Flutter specific (not a bad thing, we love Flutter :-)). We could index all templates in FileState in unlinked summary and extend AnalysisDriver to search templates by id.

[goderbauer]

@scheglov I did not have a specific UI in mind, but that would work. Although it might be hard to discover?

[xster]

Or just go-to-definition clicking a @macro going to the @template would be nice too.

[dnfield]

How about if we just scanned the Flutter repo (like we do for Snippets) and generated a (JSON?) file with key/value pairs for template name and template content? Or just create a directory with a bunch of files named after their macros.

IDEs could then just access that file/files and render the content that way without re-inventing an analysis server for docs.

[jcollins-g]

Dartdoc is already loading all the macro definitions internally and could write that out as part of normal operation. It's substantially simpler than the already existing snippet support as you don't have to keep track of where things are. Maybe add a bug to dartdoc for that?

[jcollins-g]

I'm still really concerned by all of this adding to structural debt within our tools (e.g. not debt concentrated in any one tool, but part of the way we're building our tools to interact). An "analysis server for docs" may not be strictly necessary for now but I feel like we're going to want it as more and more features of Dartdoc are desired by IDEs.

[dnfield]

Yeah, after discussing further it seems like this wouldn't be a great solution.

Another thought I have is doing something like

{@macro flutter.macro.name.whatever ref=[Class.member]}

Dartdoc would ignore the ref, and IDEs could use the ref to just put See also: [Class.member]

[gspencergoog]

/cc @christopherfujino

[devoncarew]

This functionality has been rolled into the analysis server - dartdoc hovers in IDEs now show the in-lined content from macros.

[hacker1024]

It would be nice to be able to ctrl+click them as well in the source code.