search

rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
98.58k stars 12.74k forks source link

Re-export from external crate not documented #51783

Open nyarly opened 6 years ago

nyarly commented 6 years ago

c.f. https://docs.rs/hyper/0.12.2/hyper/index.html and https://docs.rs/hyper/0.12.2/hyper/struct.Response.html

Based on that documentation, it appears that Response is part of the hyper crate, when it's definition there is https://github.com/hyperium/hyper/blob/master/src/lib.rs#L39-L48 (pub use from http).

This was especially confusing to me because I wanted to pass the result of Response::builder() between functions in my own code. I was surprised to discover that I'd need to add http as a direct dependency in my Cargo.toml.

The pub use lines referring to internal modules within hyper are reported that way, but the re-exports from http are both not listed in the "Re-exports" section, and they're presented as if they were defined in hyper.

jonas-schievink commented 5 years ago

AFAIK rustdoc will render reexported items "as if" they're placed at the reexported location if they're not reachable from anywhere else in the documented crate (which is always the case for things defined in other crates). This does make sense as it makes it easy to have a different internal organization inside the crate while still having nice documentation that hides the internal structure.

I agree it might be nice to have some indication that a type is reexported from a different crate though.

jplatte commented 3 years ago

There is a way for crates to opt out of re-exports being inlined: #[doc(no_inline)]. You could ask the hyper devs to consider applying that attribute to its http re-exports.