Funky rustdoc behavior when pub use path_to::Trait as _; for public-in-private item

[steffahn]

Something like

mod m {
    pub trait Hello {
        fn hello() {}
    }
    pub trait World {
        fn world() {}
    }
}

pub use m::Hello as _;
pub use m::World as _;

creates documentation listing two traits called "_"

both of which link to the same URL .../target/doc/crate_name/trait._.html and which contains documentation for one of the two traits, chosen seemingly at random.

When I add a few implementations, sometimes (not very reproducably) I've even gotten a weirdly broken page. E.g. I sometimes get

mod m {
    pub trait Hello {
        fn hello() {}
    }

    pub trait World {
        fn world() {}
    }

    impl World for u8 {
        fn world() {}
    }

    impl World for u16 {
        fn world() {}
    }

    impl World for u32 {
        fn world() {}
    }
}

pub use m::Hello as _;
pub use m::World as _;

to generate a page that looks like this

@rustbot label T-rustdoc, A-rustdoc-ui

[ThePuzzlemaker]

@rustbot claim
I've looked into this a bit and I've found a way to fix the main problem, but it causes a bit of a UI papercut itself--it will display the original names, but it doesn't say in any way that they've been reexported as _, so I need some advice on how I should handle this.
Using the second snippet provided with a small patch, it looks like this:

This is definitely better, but note that it does not display as pub use Hello as _ or otherwise show that it's not a full re-export. I'm not sure how exactly I should handle this, whether I should try to coerce it into displaying like regular re-exports, or add some sort of thing to show that it is not a regular re-export.

[ThePuzzlemaker]

Granted, this kind of feels like an edge case to me, I don't (personally) find any practical advantage to having a trait that you can only use the methods of but not mention or quantify over, e.g. for a fn foo<T: Trait>(x: T)-like function.

[steffahn]

I would feel like displaying it like a regular re-export feels like a good solution, and also displaying a warning that goes away by adding #[doc(no_inline)] could be a feasible approach. After all, the documentation situation when it's just the re-export documentation is somewhat suboptimal, too, because the traits are completely undocumented in this case, so a warning feels right; and after all it is a rather weird edge case that probably doesn't need special support, just obviously buggy behavior - like the current one - should be avoided.

^^^^ Just my personal opinion/interpretation right now 😉, and I haven't actually thought for more than a handful of minutes about how best to resolve this issue yet.

---

Following the approach explained above, the same thing should probably also apply for a case without public-in-private items, but with explicit #[doc(inline)] e.g.

pub trait Foo {}

#[doc(inline)]
pub use Foo as _;

should also effectively ignore the #[doc(inline)], but also issue a warning.

[steffahn]

I don't (personally) find any practical advantage to having a trait that you can only use the methods of but not mention or quantify over

I mean, I actually came up with the idea for code like this because it might have some practical use-case. It's like the ultimate sealed trait; you cannot implement it, you can't even use it in trait bounds. A bit awkward to bring into scope (since only a use path::to::module::*; will to it, but other than that, it's almost like the perfect extension trait: You're not really supposed to implement an extension trait, or to use it in a trait bound.

Of course the problems are that it's impossible to get properly documented, and it's probably confusing as hell for most users anyways, etc, so ultimately it's a bad idea.

[GuillaumeGomez]

I don't have the completely broken page:

Which rustdoc version did you use?

[steffahn]

@GuillaumeGomez I used

rustdoc 1.59.0-nightly (e100ec5bc 2021-12-21)

on Windows. I tested with

rustdoc 1.57.0 (f1edd0429 2021-11-29)

now and it gives a different-looking broken page

As mentioned above, this result is not reproducible on every build, it seems to happen randomly. Try doing cargo clean and cargo doc a few times, and you might get it. E.g. now, trying it again it took me 8 tries in a row. It's sometimes rendering a non-broken version of Hello or World, I guess the chance of the broken page at most 33%.

[GuillaumeGomez]

The rustdoc builds are reproducible normally, if not we have a much bigger issue on our hands... At this point, I wonder if the problem isn't your web browser?

[steffahn]

They aren't reproducible in this case, but I suppose the reason is just that it's because there's two different items that get documented under the same URL? If rustdoc's reproducibility relies on the fact that no two pages go to the same location, then that would make sense to me. You should more easily be able to create non-reproducible results with the original example where I noted

both of which link to the same URL .../target/doc/crate_name/trait._.html and which contains documentation for one of the two traits, chosen seemingly at random.

If you build that example yourself, multiple times (with cargo clean!), are you not getting random non-reproducible results (regarding whether the documented trait has a hello method or a world method)?!?

[GuillaumeGomez]

Oh hold on, that might be a windows-specific issue: I wonder if the file is being written from two places at the same time (we have a thread handling file writing on Windows).

[lolbinarycat]

triage: this is what it looks like now

This is a pretty pathological edge case, I don't know if we can handle this much better than we do.