Public items re-exported publicly in the same crate could have inlined docs

bb068e8
Opened by Tom Jakubowski at 2022-01-18 21:36:10

As an example of what I mean, see this page: http://doc.rust-lang.org/syntax/parse/lexer/index.html

There is a re-exports section:

pub use ext::tt::transcribe::{TtReader, new_tt_reader, new_tt_reader_with_doc_flag};

All of those items are public and reachable, so they're documented in ext::tt::transcribe. But lexer::new_tt_reader, for example, does not appear in the search index and (less seriously) it's a little annoying to have to jump through another set of links to another page to read the docs for that function.

When a private item is re-exported publicly in the same crate, or a public item from another crate is re-exported, the docs are inlined and an entry is created in the search index. I think it would be reasonable to do the same for public intra-crate re-exports.

  1. This appears to cause core::ptr::write_bytes, which is a re-export of intrinsics::set_memory , to not be listed in the index at all!

    [incidentally, I strongly dislike the write_bytes name, as it doesn't imply that all of the bytes are being set to the same value. But I guess it's too late for yak shaving.]

    comex at 2015-03-07 04:17:47

  2. This issue still exists, but I would consider it partly by design. Right now, rustdoc will create a "Reexports" section that prints each pub use that is merely a re-export of something that's already documented somewhere else. (Here's a stable link to an example, the core::ptr module in 1.19.0.) If you want to inline the documentation, you can tag the pub use with #[doc(inline)]. I haven't tested whether this includes the item in the search index with that path, but i suspect it will. Comically enough, both the intrinsics::write_bytes and the ptr::write_bytes appear in the search index in std, implying that re-exporting the module just sees the pub use as a regular item.

    I'll keep this issue open, if only for "add reexports into the search index under their new paths as well as their original ones".

    QuietMisdreavus at 2017-08-14 19:55:15