Open goderbauer opened 3 weeks ago
Real life example where flutter has these kind of library references in doc comments: https://github.com/flutter/flutter/blob/b79aabff265dce997152a4ec181337ccffe779ee/packages/flutter/lib/src/foundation/binding.dart#L57-L58
Summary: The user wants to link to the documentation of a library using @docImports
but the comment_references
lint prevents this. They propose using [foo]
to link to the library's documentation, but this functionality is currently unavailable.
It's a bit unique because the name of the library (a la library foo;
) is not anything that can be used or even referenced by code (as opposed to, say, an import prefix name). So there is no element, for example, that is provided by an import, or a shared namespace from one or more import prefixes, that represents the library. The named library is also becoming less popular, and I don't think it's a good idea to implement a feature that requires a name on a library
directive.
I think the strategy we're likely going to go with is to allow you to reference a library as its import prefix. So that you could refer to foo
with:
/// @docImport 'foo.dart' as foo;
library;
// OR:
import 'foo.dart' as foo;
/// Hello [foo].
var x = 0;
One shortcoming of this strategy is that import prefixes are not generally tied to a single import; they act as a shared namespace. I think it's not a huge shortcoming, as we can just report an "ambiguous element" warning if you try to reference [foo]
and foo
is a shared import or doc-import prefix. It might require an awkward or sub-optimal implementation, tying a prefix to the (singular) URI of the library that it's tied to. I'm open to other ideas.
Imagine we have a library as follows:
I would now like to refer to that library comment from another file/package:
I would like to have
[foo]
link to the doc on thelibrary foo;
. Currently, this doesn't seem possible withdocImport
s in a way that makes thecomment_references
lint happy.