rustdoc -- Re-export type shadowing leads to wrong doc

[Evian-Zhang]

I tried this code:

// my_crate/src/lib.rs
pub struct MyReturnType {
    pub bar: usize
}

pub fn foo() -> MyReturnType {
    MyReturnType { bar: 0 }
}

// doc_test/src/lib.rs
pub use my_crate::*;

pub struct MyReturnType {
    pub bar: u64;
}

pub fn foo2() -> MyReturnType {
    MyReturnType { bar: 0 }
}

Since Rust does not check the re-definition in re-exporting, the code compiles sucessufully.

And I use cargo doc to generate the doc of doc_test. As expected, there are foo and foo2 in the crate doc_test.

I expected to see this happen:

The return type of foo should be the MyReturnType with bar: usize as field, and the return type of foo2 should be the MyReturnType with bar: u64 as field.

Instead, this happened:

The return type of foo and foo2 are both the MyReturnType with bar: usize as field.

Meta

rustc --version --verbose:

rustc 1.42.0 (b8cedc004 2020-03-09)
binary: rustc
commit-hash: b8cedc00407a4c56a3bda1ed605c6fc166655447
commit-date: 2020-03-09
host: x86_64-apple-darwin
release: 1.42.0
LLVM version: 9.0

Severity

As suggested in naming convention, and approved by RFC #356, the Error type in each module should not have prefix. So as a common practice (such as diesel), when we want to re-export another crate, we often has the following code:

pub use another_crate::*;
pub type AnotherCrateError = another_crate::Error;

pub struct Error;

As coded above, this practice leads to the wrong doc, which may confuse the reader (such as this issue in diesel).

[aliemjay]

A live example is the docs for actix_web::error. This module defines its own struct Error which shadows actix_http:error::Error.

The problem is that struct Error now appears twice in the module page and both incorrectly link to actix_http::error::Error.

This can be very confusing to users. A related issue #88007

[aliemjay]

@rustbot claim

[jyn514]

Duplicate of #83375 (@aliemjay feel free to claim that one too :)