Closed stereotype441 closed 2 months ago
Note that Dartdoc doesn't generate a link for
other
(see https://api.dart.dev/stable/3.5.1/dart-core/List/operator_equals.html), so the only relevant functionality here is that thecomment_references
lint allows the name to be other.
Dartdoc ignores it, but navigation within an IDE will navigate to the declaration of the parameter. We do that by resolving it to a ParameterElement
. We don't have an element representing the fields in a record, so we have nothing to resolve it to and no way to navigate for those kind of references.
That isn't an argument against allowing such references, but it does mean that we'd need to do more work in the lint. The lint currently uses the presence or absence of a resolved element to decide whether or not to report the reference. That would have to change.
I'd love this. I think the more common case is desiring to refer to a function-typed element's parameter. E.g. to be able to refer to value
in Iterable.reduce
, (E Function(E combine(E value, E element))
).
Two questions:
Map<({int a, int b}), ({int a, ({int a, int b})})> Function(({int a, int b}) c, List<({int a, int b})> d)
, how to refer to each a
?comment_references
. But that lint rule depends almost entirely on analyzer's resolution. Are you specifically requesting that the lint rule separate from analyzer's resolution, and allow [foos]
, even when the analyzer does not resolve [foos]
, does not provide go-to-definition, go-to-references or renaming? Or is the request for analyzer to resolve the text as well?Without additional information we're not able to resolve this issue. Feel free to add more info or respond to any questions above and we can reopen the case. Thanks for your contribution!
Historically, it's been common to document the parameters of a method by using square brackets to refer to the parameter names. For example, the doc comment for
List.operator ==
(in the SDK) uses square brackets to refer to the parameterother
:Note that Dartdoc doesn't generate a link for
other
(see https://api.dart.dev/stable/3.5.1/dart-core/List/operator_equals.html), so the only relevant functionality here is that thecomment_references
lint allows the name to beother
.I think that if the return type of the method being documented is a record, it should be permissible to use square brackets to refer to members of the record. For example:
Similar for unnamed record elements, using the usual
$N
syntax. For example: