rustdoc: do something about reexported items

f1d88df
Opened by Simon Sapin at 2022-01-18 21:36:07

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.

  1. 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.

    Alex Crichton at 2014-07-16 22:21:12

  2. 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?

    Simon Sapin at 2014-07-17 16:28:36

  3. 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.

    Alex Crichton at 2014-07-18 00:56:07

  4. 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?

    Tom Jakubowski at 2014-07-18 05:52:59

    • 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.

    Benjamin Herr at 2014-09-05 23:20:58

  6. Triage: no change, this is still an issue.

    Steve Klabnik at 2015-09-02 20:18:11

  7. Triage: same as last year, no changes.

    Steve Klabnik at 2016-11-15 20:46:22

  8. Triage: still no change. @rust-lang/rustdoc do we plan on doing anything here?

    Steve Klabnik at 2018-09-24 17:10:09

  9. 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.

    Simon Sapin at 2018-09-24 18:59:44

  10. 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 (https://github.com/rust-lang/rust/pull/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).

    QuietMisdreavus at 2018-11-02 15:56:11