Discourage renaming in pub use re-exports

[dtolnay]

In flate2 the write/read/bufread modules all repeat the same type names:

pub use gz::EncoderReader as flate2::read::GzEncoder;
pub use deflate::EncoderReader as flate2::read::DeflateEncoder;

Unfortunately the rustdoc for flate2::read::GzEncoder shows the private names:

impl<R: Read> EncoderReader<R>
fn new(r: R, level: Compression) -> EncoderReader<R>

This is a rustdoc bug (rust-lang/rust#41072) but even aside from that, this pattern is confusing to people browsing the code because what they see clicking through a [src] link does not match how they will be using the library. Let's discourage renames in pub use unless there is a very good reason, and give an example of a very good reason from a high-quality crate.

[brson]

Add to 'naming' or 'organization'.

[dtolnay]

I don't think this is a common enough problem to need a guideline.