Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Should inner identifiers in a declaration's signature be referable in doc comments #55584

Closed
srawlins opened this issue Apr 28, 2024 · 2 comments
Labels
analyzer-ux area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. P4 type-enhancement A request for a change that isn't a bug

Comments

@srawlins
Copy link
Member

Over here, dart-lang/linter#4645, a user would like to refer to the named fields of a record type, where the record type is found either in a parameter type or return type of a function, like this:

/// [record] works, but neither does [key] or [value].
//                                    ^^^      ^^^^^ The referenced name isn't visible in scope.
({int value}) retrieveKey(({int key}) record) => (value: 1);

Should we have an algorithm for resolving inner identifiers in a signature like this?

@srawlins srawlins added area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. analyzer-ux type-enhancement A request for a change that isn't a bug P4 labels Apr 28, 2024
@lrhn
Copy link
Member

lrhn commented Apr 28, 2024

From a language perspective, those names are not names of declarations, which is what we'd traditionally allow identifiers to refer to.

That means that while ({int value}) has the identifier value in there, the identifier doesn't become part of any scope. "Referring" to it is somewhat spurious, since writing the link [value] doesn't have any scope where [value] resolves to ... well, anything.

So whatever we do here must be designed from the ground up, the language gives no help.

We could introduce a "documentation scope" which contains the same names as the declaration/parameter scope plus the names of all named record fields.
The biggest question is what happens on a conflict:

  • If the record field name has the same name as a parameter, which wins? (The parameter!)
  • If the record field name has the same name as the method itself, which wins? (...uhm...)
  • If the record field name has the same name as a surrounding top-level declaration or import, which wins? (Possibly the record field... but that's a breaking change of resolution of existing identifiers.)
  • If there are two record fields with the same name, which one wins? (Neither!)

Start with:

int foo = 42;
class Foo {
  /// Something about [foo].
  ({int foo}) foo(({String foo, int bar}) foo, (int foo, int bar) v2) => 
      (foo: foo.bar);
}

and decide what needs to change before [foo] can refer to a record field name.
(Today it refers to the positional parameter named foo, since it's resolved in the parameter scope.)

(It's also a question what it would mean to refer to a record type field name. Will "go to declaration" work? I probably can, if there is a unique resolution. What will be shown when hoovering over the reference?)

@bwilkerson
Copy link
Member

Given the ambiguities inherent in the feature, and the limited value that I currently believe it would add for users (in part because of those ambiguities), I'm comfortable saying that we won't implement such a feature at this time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
analyzer-ux area-analyzer Use area-analyzer for Dart analyzer issues, including the analysis server and code completion. P4 type-enhancement A request for a change that isn't a bug
Projects
None yet
Development

No branches or pull requests

3 participants