Description

If I have code like this in file1.dart:

class MyClass {
  int field;
}

And code like this in file2.dart:

class MyOtherClass {
  static int field;
}

And a comment like this in file3.dart:

/// Refer to [MyOtherClass.field].

And, crucially, file3.dart does not include file2.dart (but it's still a valid doc reference).

If I then rename MyClass.field to be MyClass.somethingElse using the IDE, I get the following change in file3.dart:

/// Refer to [MyOtherClass.somethingElse].

For a real world example of this, open the file packages/flutter/lib/src/material/debug.dart in the Flutter repo and insert this after the imports at the top:

class MyWidget extends StatelessWidget {
  const MyWidget({this.children = const <Widget>[]});

  final List<Widget> children;

  @override
  Widget build(BuildContext context) {
    return Column(children: children);
  }
}

Then rename children to orphans, and look at the diffs in the repo. You'll find that it modified at least four other files that are completely unrelated. This has bit me a bunch of times when I go to submit a change and see unrelated changes where I have to scratch my head and wonder where they came from.

I suspect this is because the analyzer is looking for the symbols, and since the symbols aren't imported into the file, it's just doing something "smart" with the references it finds that (sort of) match. I find it interesting that even if the symbol is a qualified symbol (e.g. [MyOtherClass.field]), it will still rename it.

I wish it wouldn't do these unknown symbol doc comment link renames, or at least that it would ask me before doing it.

IntelliJ doesn't have this problem, I think because if it can't tell for sure that a symbol matches (no analyzer link for it, I think), it'll go to an intermediary mode where it asks for confirmation and you can skip some of the renames. It groups them into "comments", "doc comments" and "code" too, so you can just skip the unrelated comment changes. It's annoying to hit that confirmation mode, but I haven't had problems with unrelated changes like this.