What can be referenced in a documentation comment reference?

[srawlins]

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.

• I will try and fix this problem on dart.dev.

[srawlins]

This documentation specifically would be timely now as we're adding the "Documentation imports" feature for the analyzer and dartdoc: dart-lang/sdk#56186.

If this team indicates that documentation would be accepted, I can start working on a PR 😁

[parlough]

Yes this is something that I've long wanted, so it would definitely be accepted :D. There are some other dartdoc related things I'd like to document, so I'll give some thought on the best place for it.

Feel free to place the docs on their own page for now, perhaps under /src/content/tools.