Document why std docs have many apparent duplicates

[mdinger]

Reddit thread:

Why are data structures generally duplicated in the rust standard library, or at least apparently so in the API documentation?

e.g. std::string::String vs. collections::string::String, std:fmt::String vs. core::fmt::String, std::vec::Vec vs. collections::vec::Vec?

I'm not certain which of these the user was referring to but both could be possibly weird at first appearance:

• Why is String in std::string and collections::string and others
• Why is String in string and Vec in vec

It was suggested that this be included in a How to read this documentation somewhere. If it was written, I would imagine it should be automatically included in the rust std documentation system so that it is included in all rust derived projects like gfx-rs and piston documentation.

cc: @steveklabnik

[sfackler]

I think what would make sense here is to move the documentation for all of the std reexported crates (core, alloc, etc) out of the "main" API docs into a separate set. That way the "normal" use case of just using std will be more straightforward, as will the other use case of running with #[no_std], since both groups will only be searching the docs that apply to them.

[mdinger]

Sounds fine to me. If that is the consensus or desired approach, let me know and I'll try to update the Title/description accordingly if it matters as I won't be able to help with much else for this. I don't know how much discussion is needed before a decision is made anyhow.

[rpjohnst]

A more general solution might be to link re-exports in the docs to their original source, so that you can look in the std docs and see everything labeled as a re-export specifically from core or collections or wherever.

The only issue might be when something is re-exported from somewhere private, which could just be special-cased. Or maybe the documentation could be placed at the re-export that the library writer wants it at.

I'd prefer that over separating the docs, and it would work better for third party libraries as well.

[Kimundi]

Whether or not a definition is a re-export from a different crate is a user visible property, because all possible paths to the same item are interchangeable:

extern crate core;
let _: std::option::Option<uint> = core::option::Some(0u);

Because of that it is my opinion that the docs should always provide a full chain of links for each reexport step, skipping/hiding all private ones in the chain:

// my_crate
pub use self::pub_mod::Foo;
pub mod pub_mod {
     pub use self::priv_mod::Foo;
     mod priv_mod {
         pub struct Foo;
    }
}

This should show you both ::Foo and ::pub_mod::Foo in the docs, mention that ::Foo is a reexport of ::pub_mod::Foo and mention that that is a reexport of a private type as well (Or just tread the last public link in the chain as the original definition)

For ergonomic reasons every reexport should probably show the docs of their item directly inline in the documentation as if the item where defined there, but also put a clearly visible info at the top that this is a reexport, including links to the the next link in the reexport chain:

Enum std::option::Option

Reexported from core::option::Option

Original docs...

Related to this, the rustdoc search should group things that are exports of each other together, or hide them by default.

Instead of this:

Results for Option

std::option
std::option::Option
std::os::MapOption
std::ptr::RawPtr::to_option
core::iter::MinMaxResult::into_option
std::option_env!
std::sync::atomic::AtomicOption
std::sync::atomics::AtomicOption
std::rand::Rng::choose_option
rand::XorShiftRng::choose_option
rand::isaac::IsaacRng::choose_option
rand::reseeding::ReseedingRng::choose_option
core::option
core::option::Option
rustc::driver::config::Options
getopts::Occur::Optional
core::ptr::RawPtr::to_option

It should look kinda like this:

Results for Option

std::option

• core::option

std::option::Option

• core::option::Option

std::os::MapOption
std::ptr::RawPtr::to_option

• core::ptr::RawPtr::to_option

core::iter::MinMaxResult::into_option
std::option_env!
std::sync::atomic::AtomicOption

• std::sync::atomics::AtomicOption

std::rand::Rng::choose_option
rand::XorShiftRng::choose_option
rand::isaac::IsaacRng::choose_option
rand::reseeding::ReseedingRng::choose_option
rustc::driver::config::Options
getopts::Occur::Optional

[thestinger]

I don't think we should explain why the standard library is poorly designed. The problem should be fixed by not making confusing mazes of re-exports. Crates should just be used directly and the prelude could include those crates and use directly from them instead of the current mess.