Support go-to-definition on macro references within dart documentation comments

[osaxma]

Currently, Flutter source code is filled with @macro references within its documentation comments. While reading the code and drilling in using an IDE, it becomes difficult to read the actual documentations since they are not located above their definition.

In some cases, the entire documentation comment is located elsewhere:

  /// {@macro flutter.widgets.editableText.strutStyle}
  final StrutStyle? strutStyle;

  /// {@macro flutter.widgets.editableText.textAlign}
  final TextAlign? textAlign;

  /// {@macro flutter.widgets.editableText.textDirection}
  final TextDirection? textDirection;

In other cases, a segment of the documentation is located elsewhere (i.e., {@macro flutter.widgets.State.initState})

  /// Called whenever the widget configuration changes.
  ///
  /// If the parent widget rebuilds and request that this location in the tree
  /// update to display a new widget with the same [runtimeType] and
  /// [Widget.key], the framework will update the [widget] property of this
  /// [State] object to refer to the new widget and then call this method
  /// with the previous widget as an argument.
  ///
  /// Override this method to respond when the [widget] changes (e.g., to start
  /// implicit animations).
  ///
  /// The framework always calls [build] after calling [didUpdateWidget], which
  /// means any calls to [setState] in [didUpdateWidget] are redundant.
  ///
  /// {@macro flutter.widgets.State.initState} 
  ///
  /// If you override this, make sure your method starts with a call to
  /// super.didUpdateWidget(oldWidget).
  @mustCallSuper
  @protected
  void didUpdateWidget(covariant T oldWidget) { }

The main pain point above is having to manually search for the definition in a project that's not part of the workspace.

Ideally, it'd be preferable if documentation is actually shown above its definition, and I hope that will be taken into consideration.

But for this request, it'd be useful to support go-to-definition on {@macro some.refrence.to.some.definition} so it can be supported by IDEs. This way drilling into the code and documentation will be easier than having to search for the definition outside the workspace.

[rydmike]

Plus one for this improvement proposal.

This did not use to be an issue as most documentation comments in Flutter were not using macros earlier, on the other hand it then meant that repeated/duplicated documentation comments had to be maintained in multiple places and might become outdated. So the increased macro usage is certainly understandable from that point of view as it it enables maintaining a single source of documentation "truth".

However, they really make drilling into classes and their properties in the Flutter SDK to quickly find the documentation a lot less useful than it used to be. To the point where it no longer is very practical or useful at all.

Please consider improving the developer experience on this.

Minimum requirement would be a click through to actual macro definition, but certainly even better if the primary supported IDE's Studio/IntelliJ and VS-Code could expand the macros directly inline without need to drill into where they are actually defined.

[lukepighetti]

Many of my field comments are

/// See [IconButton.icon]

Would be nice if we could have a similar syntax for macros. Would want that "copied from X" notice like on @override field comments.

Not sure if this is what you're tracking in this issue or not.

[Jonas-Sander]

Instead of adding complexity at the IDE level as a flutter user I would much rather have comments everywhere (not following macros). In this way I don't have any problems looking at the source code from any program or even from github directly.

Maybe there could still be the macros, but with the actual comment underneath/on top? There then may be an additional processing step of the CI-Pipeline where it is checked that the docs are up to date everywhere?
This would make the development on flutter maybe a bit harder but would bring a big benefit for all the flutter users. Maybe there could be a pre-commit hook where the docs are updated before checking something in or something along those lines... I'm sure one can get tooling that would alleviate most of the pain.

[rydmike]

@Jonas-Sander I like this idea too, it would be universal and like you say work regardless off IDE tooling and thus for GitHub reading too. Definitely my preferred choice as well, good suggestion! 💙

[bwilkerson]

Any changes to the way documentation comments are handled in Flutter would come from the Flutter team. I encourage you to open an issue to request this change at https://github.com/flutter/flutter.

[rydmike]

@bwilkerson Thanks for the suggestion and done: https://github.com/flutter/flutter/issues/77607

[devoncarew]

I'll keep this issue open - it sounds like we may want either this issue to be addressed of the flutter/flutter one.