Figure out a way to link to downstream crates

[jyn514]

After #73101 there is no way to link to items in downstream crates. This is fairly common to try; futures does this extensively (#64193), as does core/std (#73423).

On one hand, this clearly breaks rust's scoping rules: inner crates can't refer to the types of their dependencies because it causes a cyclic dependency. So there's an argument to be made for saying this is just not supported.

On the other hand, this seems really useful. In fact it used to work for re-exports from the inner to outer crate, but only when you documented both crates at the same time, and the outer crate after the inner crate (this was #73699). So it would be great to find a way to make it work.

cc @Manishearth, @Nemo157

[jyn514]

@Nemo157 also suggested that this be supported through cargo:

nemo157: One thing I mentioned a long time ago was that a concept of doc-dependencies would be useful, so that you could link to other crates just while building your documentation. My original use case being for futures-util to be able to link up to the futures facade in places
jynelson: how would that work with cyclic dependencies? does cargo allow that?
nemo157: they wouldn't have to be necessarily cyclic, futures-util(doc) would depend on futures(lib) would depend on futures-util(lib)
nemo157: similar to how you can have what looks like cyclic dependencies with dev-dependencies
jynelson: isn't futures-util(doc) the same crate as futures-util(lib) from the perspective of rustc?
or does it not matter about rustc and we only care about cargo?
nemo157: it might be now, but I think it could be setup that the current crate is built into metadata, then that metadata is passed to rustdoc when building the doc

[Manishearth]

I don't think cargo would support something like that. That still introduces a cyclic dependency, even if it's technically feasible. Cargo doesn't really distinguish in the crate graph

[Nemo157]

It would be good to clarify "upstream", my assumption would be that an "upstream crate" is a dependency, which should work with intradoc links?

[jyn514]

Oops, yeah I got upstream and downstream mixed up.

[Nemo157]

@Manishearth cargo already allows "cyclic" dependencies for dev-dependencies, since they're not really cyclic in its build graph. Changing it to pass the current crate and dependents of it in as metadata when it calls rustdoc seems relatively trivial. The rustdoc side changes to support a sort of mixed source-files+metadata for the crate being documented is more difficult (especially with cfg(doc)), and after thinking about it more since the above discussion I'm not sure if it's actually feasible.

[Manishearth]

@Nemo157 it's not trivial: dev-dependencies are dependencies of the test crates, which are independent crates. That's not the case for docs.

even if we somehow solve this in cargo, the rustc infrastructure rustdoc relies on would not work.

[Manishearth]

So another thought I had: Perhaps the solution for this is not in intra doc links. I'm not a fan of making intra doc links behave outside of the scope of paths and having forward decls: it's a major infrastructure change for rather minor benefit. The only main place that benefits is std which is designed as a facade crate.

An alternate idea is to have a $DOC_ROOT, i.e. you can define links as [foo]: $DOC_ROOT/std/blah. These are only for forward decls, and they require a feature gate that we do not plan to stabilize.

Thoughts? @rust-lang/rustdoc

[jyn514]

This does not solve the more general case of linking to downstream crates :/ I'm ok with working around this for std but I'd like to eventually have something that works for futures and other non-std crates.

[Manishearth]

I kind of feel like there shouldn't be such a solution for other crates.

Though I'd be open to eventually stabilizing DOC_ROOT