support some form of fully qualified references in dartdoc documentation

[devoncarew]

See dart-lang/dartdoc#1153 for more discussion and background.

We'd like to be able to refer to symbols in dartdoc references without having to add imports just for those references. Examples of a fully qualified scheme are [widgets.Draggable] or [package:flutter/widgets Draggable], but I don't think the exact scheme matters for the purposes of fixing this bug.

/cc @scheglov @bwilkerson

[scheglov]

I'm on the fence about this feature.

On one hand, this is something useful for our users.

OTOH, implementation would require us to look for URIs to import not only in import directives, but also in comments. And these import URIs are special - we don't need full resolution for them. Or we do need, if the referenced element is a field for which type inference should be done. So, it would be as expensive for analysis as adding this libraries are real imports. And we would need to add this dependency into summaries, so we will add a dependency cycle and might get bitten in Bazel :-(

[zoechi]

@devoncarew why do you think these "inline" imports are better?
Is this to prevent files being imported at runtime that are actually not required or is this just about more convenient syntax?

[devoncarew]

Thanks for the context on the implementation complexity. I would prefer not to make analysis more complex for the sake of this feature.

Are there alternative implementations - compromises in how the references could be used or defined - that wouldn't have negative implementation implications?

[bwilkerson]

If you want analyzer to be able to resolve the references so that dartdoc can produce links to the referenced entities, then it has to know where the reference is defined, which is equivalent to having an import. So, no, I can't think of any way to get what you want without the overhead.

[pq]

/cc @jcollins-g