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

[srawlins]

Over here, #59237, 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?

[lrhn]

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]

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.