Skip to content

intra-rustdoc-link: Cannot use core in core crate #73445

Open
@tesuji

Description

@tesuji
Contributor

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

Activity

tesuji

tesuji commented on Jun 17, 2020

@tesuji
ContributorAuthor

Note: Document build pass in user crate:

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

jyn514 commented on Jun 17, 2020

@jyn514
Member

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

jyn514

jyn514 commented on Jun 17, 2020

@jyn514
Member

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

Manishearth

Manishearth commented on Jun 17, 2020

@Manishearth
Member

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

Manishearth

Manishearth commented on Jun 17, 2020

@Manishearth
Member

@jyn514 no, it's not a markdown issue

jyn514

jyn514 commented on Jun 17, 2020

@jyn514
Member

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

added
A-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by name
D-confusingDiagnostics: Confusing error or lint that should be reworked.
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Jun 17, 2020
jplatte

jplatte commented on Jun 17, 2020

@jplatte
Contributor

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).

changed the title [-]Cannot use intra-doc-link in core crate[/-] [+]intra-rustdoc-link: Cannot use core in core crate[/+] on Jun 17, 2020
tesuji

tesuji commented on Jun 17, 2020

@tesuji
ContributorAuthor

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

Manishearth

Manishearth commented on Jun 17, 2020

@Manishearth
Member

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

tesuji

tesuji commented on Jun 18, 2020

@tesuji
ContributorAuthor

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.

26 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameD-confusingDiagnostics: Confusing error or lint that should be reworked.S-blockedStatus: Blocked on something else such as an RFC or other implementation work.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @jplatte@Manishearth@tesuji@jyn514@rustbot

        Issue actions

          intra-rustdoc-link: Cannot use core in core crate · Issue #73445 · rust-lang/rust