Doc comments could feel more "first class" if auto-complete/checking worked in IDEs

[matanlurey]

See the following example:

final class Constitution extends Ability {
  /// An alias for [AbilityKind.constitution].
  static const kind = AbilityKind.constitution;

  /* rest omitted. */
}

1. If I select .constitution and start typing over it, i.e. .^d, I'll get dexterity suggested to me.
2. If I mistype .dexxterity it will be marked as a diagnostic.

In the [ ... ]-comments, 1 does not work and 2 does (indirectly) through the comment_references lint (as an side, I'd love to see https://dart.dev/tools/linter-rules/comment_references become part of the analyzer by default with the "right" rules).

/cc @srawlins

[matanlurey]

Oh, and rename doesn't work, that would be nice too :)

[parlough]

I'm not sure what iteration/version of the design is the most current, but a lot of this is dependent on or at least discussed in #50702.

[gnprice]

For me this often does work already, in Android Studio with the Dart plugin (and the Flutter plugin, but that one's probably not involved). In particular, (1) works great for me in the case of enum values, which are what appear to be in your example. Are you using Android Studio or a different IDE?

Similarly "rename" works great — if I rename some variable, function, etc., then references to it in dartdoc get updated too. (Presumably it only works for references that were successfully resolved, which pending #50702 isn't as comprehensive as one would like it to be.)

If it's working for me in Android Studio / IntelliJ but not you when using a different IDE, then it's likely this is an issue for the IDE plugin.

[bwilkerson]

1. If I select .constitution and start typing over it, i.e. .^d, I'll get dexterity suggested to me.

I extended your example slightly in order to have error-free code to start from:

final class Constitution extends Ability {
  /// An alias for [AbilityKind.constitution].
  static const kind = AbilityKind.constitution;

  /* rest omitted. */
}

class Ability {}
enum AbilityKind {constitution, dexterity}

I might have guessed wrong about how Ability and AbilityKind are declared, and that might account for the difference, but using an SDK built from HEAD code completion (after AbilityKind.) worked in both locations.

... (as an side, I'd love to see https://dart.dev/tools/linter-rules/comment_references become part of the analyzer by default with the "right" rules).

As Parker noted, this is dependent on work that we're currently doing to remove some of the special case handling that dartdoc does (inferring resolutions for un-imported references in doc comments) so that all of our tooling can have the same sematics. Until then the analyzer won't be able to know, without dartdoc's whole-world assumption, whether the reference is valid or not. As part of this work we'll convert the lint to a warning.