Discourage awkward reexports in favor of pub(restricted).

[dragostis]

Instead of having awkward structures like:

my_mod_private/
  stuff/
other_mods_see_private_stuff/

and in lib.rs:

mod my_mod {
    // reexport what needs to be public from my_mod_private
}

we should make use of pub(restricted) (stabilized in 1.18).

[brson]

Seems like we need a concrete place where we've done this, and have a concrete pattern to suggest.

[dtolnay]

Thanks! I added a note about pub(restricted) in 2fb6161. For the purpose of the API guidelines this is only about removing things from the public API. I don't want to go into much more detail about advanced use of pub(restricted) because none of that affects the crate's API.