Reference libraries with @docImports

[goderbauer]

Imagine we have a library as follows:

/// Long and extensive documentation about this library
library foo;

// Good stuff in this library.

I would now like to refer to that library comment from another file/package:

/// Bla bla bla.
///
/// The details are explained in the [foo] library.
void bar() {
  // ...
}

I would like to have [foo] link to the doc on the library foo;. Currently, this doesn't seem possible with docImports in a way that makes the comment_references lint happy.

[goderbauer]

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

[dart-github-bot]

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.

[srawlins]

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.