Repository navigation
rustdoc: do something about reexported items #15723
Description
Activity
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.
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 theith byte of a string.
collections::str::StrSlice::char_at Plucks the character starting at theith byte of a string.
core::str::StrSlice::char_at Plucks the character starting at theith byte of a string.
collections::str::StrSlice::char_at_reverse Plucks the character ending at theith byte of a string.
core::str::StrSlice::char_at_reverse Plucks the character ending at theith 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?
- changed the title
[-]rustdoc shouldn’t document reexports separately[/-][+]rustdoc: do something about exexported items[/+]on Jul 17, 2014 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.
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?
- changed the title
[-]rustdoc: do something about exexported items[/-][+]rustdoc: do something about reexported items[/+]on Jul 29, 2014 - 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::fooand then re-exported aslibname::foo. afaict, search only turns up the former while I'd assume that I'm really expected to use the latter.Triage: no change, this is still an issue.
Triage: same as last year, no changes.
Reacted by Benjamin HerrTriage: still no change. @rust-lang/rustdoc do we plan on doing anything here?
We now have
#[doc(inline)]and#[doc(no_inline)]to control this, so I suppose this issue should be about reviewing how these attributes are used and should be used in the standard library.In addition, the documentation for B::C should list all the known name it is re-exported as (in this case A::C).
As you mentioned in the OP, this gets complicated across crates, but we do have precedent for adding things to a dependency's documentation: trait implementors. If two crates are documented into the same output directory, trait implementations between those two crates will fill a JavaScript file that is dynamically loaded by the parent trait to list implementations in "downstream" crates. This does only work for crates in the same "doc bundle" (my term for "crates documented at the same time into the same target directory), but for situations like the std facade (or other facade patterns if they don't defer documentation to docs.rs) it can work out.
There was another issue mentioned in the thread about the duplicate re-exports showing up in the search index. That is also a problem of the crates being documented into the same "doc bundle", since each will fill the search index independently. However, there is currently an open PR (#54706) that allows users to restrict their searches to a specific crate, which may help cut down somewhat. In addition, i believe that results from the same crate you're currently looking at are prioritized above other crates' results now, so patterns like the std facade will show the "proper" item first if you're starting from std. However, this doesn't prevent duplicates from the same crate showing up, which would still be a problem.
I'm open to allowing a way to tell rustdoc that a certain location is the "canonical" one, for the purposes of inlining, or for showing the path when an item is referenced, or the like. I'm not super sure how to deal with cross-crate re-exports in that case, but it will help the situation where an item is defined into a private module, then exported from two public ones (say, a prelude and the "real" location that it should be referenced from).
Reacted by José Luis Cruz
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
StrSlicetrait 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
Acontains apub use B::C;statement:A::CAshould link to the original documentation forB::CB::Cshould list all the known name it is re-exported as (in this caseA::C).It gets more complicated when
AandBare not in the same source repository, but IMO still worth pursuing. Sphinx does support cross-references to other repos.