What can be referenced in a documentation comment reference? #6076
Labels
co.request
Community ask for documentation
d.enhancement
Improves docs with specific ask
e2-days
Can complete in < 5 days of normal, not dedicated, work
from.user
Issue raised by user
p2-medium
Necessary but not urgent concern. Resolve when possible.
t.diagnostics
Relates to diagnostics, analysis, or linting of code
What information needs to be added?
There are some corners to what can be referenced in a doc comment reference (
/// [...]
). For example, an instance member can be referenced, qualified by it's enclosing class's name (e.g.[Future.then]
, even though that is not a static member).A generic type can be referred to by it's "base" name (
[List]
) but not with type arguments ([List<int>]
). For a comment on a function, the function's parameters are in-scope. An unnamed constructor can be referred to by it's tear-off name ([Completer.new]
). Doc imports add a scope. Imported elements can be referenced by their import prefix, if they have one ([async.Future.value]
). Etc.CC @dart-lang/analyzer-team
Where should this new content appear?
As far as I can tell, outside of Effective Dart, there is only one sentence on comment references between square brackets: https://dart.dev/language/comments#documentation-comments. This page is short, so the content could be another section on the page, or a separate page.
I would like to fix this problem.
The text was updated successfully, but these errors were encountered: