intra-doc links: re-exports are not resolved properly. Unclear scope of re-exports(?)

[realaravinth]

I'm trying to migrate actix-http to intra-doc. The docs generated by re-export of HeaderMap doesn't have one of it's structs(GetAll )linked properly

Code

There are two files involved: src/header/map.rs containing the definition and src/lib.rs containing it's re-exports.

• src/header/map.rs:

pub struct HeaderMap {
    pub(crate) inner: FxHashMap<HeaderName, Value>,
}
impl HeaderMap {
   ...
    /// Returns a view of all values associated with a key.
    ///
    /// The returned view does not incur any allocations and allows iterating
    /// the values associated with the key.  See [`GetAll`] for more details.
    /// Returns `None` if there are no values associated with the key.
    pub fn get_all<N: AsName>(&self, name: N) -> GetAll<'_> {
    ...
    }
}
pub struct GetAll<'a> {
    idx: usize,
    item: Option<&'a Value>,
}

• src/lib.rs:

pub mod http {
    //! Various HTTP related types

    // re-exports
   ...
    pub use crate::header::HeaderMap;

    /// Various http headers
    pub mod header {
        pub use crate::header::*;
    }
...
}

I expected to see:

the correct page linked for GetAll

Instead

I saw [GetAll]

Screenshot: https://i.imgur.com/fVPqaS4.png

My understanding of the problem:

The documentation string expects GetAll to be in the same scope-level(is that a word?:D) as HeaderMap but when re-exporting, these scope-levels can't be guaranteed.

In my case, two documentation pages are generated: one at the place of definition and the other at the re-export. The definition page works fine because it has GetAll scoped in the save level. But in the re-export, HeaderMap and GetAll have different scopes. HeaderMap is http::HeaderMap and GetAll is http::header::map::GetAll(re-exported scope) or crate::header::map::GetAll. The documentation string breaks in the re-export because of it.

Re-exporting crate::header::map::GetAll in inside mod http(in src/lib.rs) fixes the issue though.

Meta

rustc --version --verbose:

rustc 1.49.0-nightly (25f6938da 2020-11-09)
binary: rustc
commit-hash: 25f6938da459a57b43bdf16ed6bdad3225b2a3ce
commit-date: 2020-11-09
host: x86_64-unknown-linux-gnu
release: 1.49.0-nightly

cc @jyn514

[jyn514]

Hmm, I thought I fixed this a while ago in #73101.

[jyn514]

I can't reproduce this issue:

// outer
pub mod http {
    //! Various HTTP related types

    // re-exports
    pub use crate::header::HeaderMap;

    /// Various http headers
    pub mod header {
        pub use crate::header::*;
    }
}

mod header {
    pub use iter::HeaderMap;
}

// inner
pub struct HeaderMap {
    pub(crate) inner: std::collections::HashMap<usize, usize>,
}

impl HeaderMap {
    /// Returns a view of all values associated with a key.
    ///
    /// The returned view does not incur any allocations and allows iterating
    /// the values associated with the key.  See [`GetAll`] for more details.
    /// Returns `None` if there are no values associated with the key.
    pub fn get_all(&self) -> GetAll<'_> {
        unimplemented!()
    }
}

pub struct GetAll<'a> {
    idx: usize,
    item: Option<&'a usize>,
}

[jyn514]

Are you sure you're using nightly rustdoc? intra-doc links won't be stable for another week.

[jyn514]

If you can send the output from RUSTDOC_LOG=rustdoc::passes=info cargo +nightly doc, that would also be helpful. You'll need to touch src/lib.rs because cargo doesn't invalidate the incremental cache (rust-lang/cargo#8374).

[realaravinth]

I apologies for the troubles. I did a rustup update last night when I wrote the report, I should've ran it in the morning before filing it. I ran ran the update and it works now. Thanks!