Rust: intra-rustdoc-link: Cannot use core in core crate

[lzutao]

I tried to document this code in libcore (./x.py doc src/libcore):

impl<T: Deref, E> Result<T, E> {
    /// Converts from `Result<T, E>` (or `&Result<T, E>`) to `Result<&<T as Deref>::Target, &E>`.
    ///
    /// [`core::ops::Deref`]
    pub fn as_deref(&self) -> Result<&T::Target, &E>;
}

I expected to see the above code build pass.

Instead, this happened: Build failed the following errors:

 Documenting core v0.0.0 (/home/lzutao/fork/rust/compiler/src/libcore)
error: `[core::ops::Deref]` cannot be resolved, ignoring it.
    --> src/libcore/result.rs:1151:68
     |
1151 |     /// Coerces the [`Ok`] variant of the original [`Result`] via [`core::ops::Deref`]
     |                                                                    ^^^^^^^^^^^^^^^^^^ cannot be resolved, ignoring
     |
note: the lint level is defined here
    --> src/libcore/lib.rs:64:9
     |
64   | #![deny(intra_doc_link_resolution_failure)] // rustdoc is run without -D warnings
     |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

error: Could not document `core`.

cc #43466
cc @Manishearth @GuillaumeGomez @jyn514

[lzutao]

Note: Document build pass in user crate:

/// Intra link testings
///
/// [`Deref::Target`](core::ops::Deref)
pub struct Foo;

[jyn514]

What happens if you use crate::ops::Deref instead?

[jyn514]

Actually this might be a markdown issue, does [Deref::Target](core::ops::Deref) work in libcore?

[Manishearth]

@lzutao core::ops::Deref will never work in the core crate, crates do not know their own names typically

[Manishearth]

@jyn514 no, it's not a markdown issue

[jyn514]

@rustbot modify labels: T-rustdoc A-intra-doc-links D-confusing

[jplatte]

crates do not know their own names typically

Which can be worked around with an extern crate self as foo; in the crate root, in case anybody needs that (I've previously required it to get a proc macro working both inside its "parent crate" and outside of it).

[lzutao]

Oh, using [`crate::path`] works correctly. It is kind of confusing through.

[Manishearth]

I don't see how: cratename::foo _never_ works in paths within the same crate

[lzutao]

I cannot use std:: doc link prefix also.

 Documenting core v0.0.0 (/home/lzutao/fork/rust/compiler/src/libcore)
error: `[std::ops::Deref]` cannot be resolved, ignoring it.
    --> src/libcore/result.rs:1151:77
     |
1151 |     /// Coerces the [`Ok`] variant of the original [`Result`] via [`Deref`](std::ops::Deref)
     |                                                                             ^^^^^^^^^^^^^^^ cannot be resolved, ignoring
     |

@Manishearth

cratename::foo never works in paths within the same crate

You have a point. But for me what makes this confusing is that in doctest
I have to import items by crate name. But in doc link I don't have to.

[jyn514]

doctests are separate crates that have the original as a dependency. This is the reason you can't have doctests for private functions even if they're pub(crate).

[lzutao]

Yes, that's understandable. But a note or help message in case resolve links fail could help.

[Manishearth]

@lzutao well, yes, core does not have a std in it's dependencies

[Manishearth]

Doctests are separate crates and this distinction comes up quite often anyway so I'm not sure if it needs to be fixed in intra doc links, I'd also be surprised if folks didn't know it as well.