rustdoc: do something about reexported items

[SimonSapin]

Update: This issue was first filed with the title "rustdoc shouldn’t document reexports separately", but that might not be the desired solution.

---

For example, the StrSlice trait is currently documented in three different places:

http://doc.rust-lang.org/std/str/trait.StrSlice.html
http://doc.rust-lang.org/collections/str/trait.StrSlice.html
http://doc.rust-lang.org/core/str/trait.StrSlice.html

It really is the same trait, but in the documentation they appear as distinct.

I think that, when module A contains a pub use B::C; statement:

• rustdoc should not create a new documentation page for A::C
• Instead, the documentation for A should link to the original documentation for B::C
• In addition, the documentation for B::C should list all the known name it is re-exported as (in this case A::C).

It gets more complicated when A and B are not in the same source repository, but IMO still worth pursuing. Sphinx does support cross-references to other repos.

[alexcrichton]

It was a very explicit design decision, and there is quite a lot of support, to inline documentation across crates, creating new pages. The whole point of the std facade was to make it exactly appear as if there were no facade, requiring inlining of documentation.

That being said, it could be the case that rustdoc could do a better job of presenting that information, which is what I believe this bug should be about rather than preventing inlining.

[SimonSapin]

Ok, maybe the solution is not the one I suggested, but I hope you agree there is an issue when, for example, a search gives three times as many results as there really are distinct items:

http://doc.rust-lang.org/std/?search=char_at

Results for char_at

std::str::StrSlice::char_at Plucks the character starting at the ith byte of a string.
std::str::StrSlice::char_at_reverse Plucks the character ending at the ith byte of a string.
collections::str::StrSlice::char_at Plucks the character starting at the ith byte of a string.
core::str::StrSlice::char_at Plucks the character starting at the ith byte of a string.
collections::str::StrSlice::char_at_reverse Plucks the character ending at the ith byte of a string.
core::str::StrSlice::char_at_reverse Plucks the character ending at the ith byte of a string.

Perhaps libstd is a special case, and another approach would be to not document at all on http://doc.rust-lang.org/ crates that are entirely re-exported through libstd?

[alexcrichton]

I do indeed think this is a problem, but it's a problem that can be solved in the frontend without compromising documentation as a whole.

[tomjakubowski]

The problem is with the redundant results in the search index. Maybe re-exported items in the search index could indicate the path of the original item, which would then (optionally?) be hidden from search results?

[ben0x539]

• In addition, the documentation for B::C should list all the known name it is re-exported as (in this case A::C).

imo we really want something like this at least for cases where some item is defined in libname::some::hierarchy::of::internal::modules::foo and then re-exported as libname::foo. afaict, search only turns up the former while I'd assume that I'm really expected to use the latter.

[steveklabnik]

Triage: no change, this is still an issue.

[steveklabnik]

Triage: same as last year, no changes.