rustdoc: Structured suggestion for intra-doc links based on current crate name

[joshtriplett]

Within a crate xyz, the link [`xyz::path::some_item`] gives an error. This would be challenging to fix in the rustdoc resolver. However, we could provide a rustfix-applicable structured suggestion on the error, suggesting [`xyz::path::some_item`][`crate::path::some_item`].

[jyn514]

Oh, I was proposing that rustdoc suggest extern crate self as xyz; in the crate root, which means you only have to do it once instead of for each link. But suggesting [crate:: also works.

[jyn514]

Note that rustfix currently doesn't work for rustdoc: rust-lang/cargo#13025

[joshtriplett]

@jyn514 Suggesting the extern crate solution seems potentially workable, though it's unfortunate to suggest the use of extern crate when it's otherwise unneeded in Rust 2018.

Perhaps use crate as xyz;? (Or use crate::self as xyz; if use crate doesn't work?)

[jyn514]

Perhaps use crate as xyz;?

Oh nice, I didn't expect that to work. Yes, that sounds better :)

//! [playground::f]
use crate as playground;

pub fn f() {}

[jyn514]

Oh wait, that only works for the top-level, it doesn't affect submodules:

use crate as playground;

mod inner {
    //! [playground::inner::f] //~ ERROR no item named `playground` in scope
    pub fn f() {}
}

So I do think the extern crate self approach works better here.

[camelid]

Oh wait, that only works for the top-level, it doesn't affect submodules:

use crate as playground;

mod inner {
    //! [playground::inner::f] //~ ERROR no item named `playground` in scope
    pub fn f() {}
}

So I do think the extern crate self approach works better here.

Yeah, stuff in the parent module (like uses) doesn't usually show up in child modules.