Repository navigation
Stabilization of the documentation scope in rustc #163896
Description
Stabilization of the documentation scope in rustc
rustdoc is in the process of stabilizing --remap-path-scope in rustdoc in #163895. (We stabilized --remap-path-scope in rustc earlier this year in #147611).
Summary
In addition to the other stable scopes (diagnostics, debuginfo, object, ...), rustdoc has an additional scope: documentation, it's used to define if paths should be remapped in the documentation.
In order to simplify interoperability between rustc and rustdoc, the scope is being proposed to be accepted by rustc.
The scope is never checked to be active by rustc, but it still encoded in rmeta. This is so rustdoc can check if the documentation scope is active for a RealFilename when getting the filepath of a RealFilename coming from a dependency.
Activity
Urgau commentedon Oct 6, 2026
@rfcbot merge compiler
rust-rfcbot commentedon Oct 6, 2026
@Urgau has proposed to merge this. The next step is review by the rest of the tagged team members:
No concerns currently listed.
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!
See this document for info about what commands tagged team members can give me.
oli-obk commentedon Oct 7, 2026
why is it necessary for rustc to accept this flag? simply forwarding all rustdoc flags to rustc without filtering?
Urgau commentedon Oct 7, 2026
The flag (
--remap-path-scope) is stable inrustc, that's not something new or something that's changing.The flag has multiple options that can be passed to it, we called them scopes. All the scopes currently stable do something in
rustc.What's changing is it rustdoc is stabilizing the flag on their side, but to avoid using a misleading scope, like
diagnosticsfor the generated documentation html files by rustdoc, we created a new scope in rustc/rustdoc:documentation.It's this new scope, and only this new scope, that will do nothing in rustc it-self.
As for why
rustcshould accept it, it's both to simply interoperability, it's easier for users if rustc and rustdoc accept the same options.But there also is a more practical use, rustdoc uses the same
rmetafrom the dependencies and those may contain paths thatrustdocmay want to print the remapped path (not sure if we have a stable case in rustdoc for that though).oli-obk commentedon Oct 7, 2026
I thought rustdoc already had options that rustc doesn't accept. But even if not, where is such "interop" (do you mean drop-in replacement?) useful or already in use?
How does that relate to the flags? If rustc built the rmeta, it didn't get remapped, so rustdoc needs to do sth here anyway
Urgau commentedon Oct 7, 2026
rustdochas flags thatrustcdoesn't have, but I don't thinkrustdochas anyrustdocspecific options in a shared flag.Rust-for-linux is not currently using
--remap-path-scopein rustdoc but they do consider the flag to be "common". Just like--remap-path-prefixis.https://github.com/torvalds/linux/blob/602042bf29f6efde39cfb5fdd9289bf4854bc0c5/rust/Makefile#L176
The scopes are attached to each individual
RealFilenamein thermetaat https://doc.rust-lang.org/stable/nightly-rustc/rustc_span/struct.RealFileName.html. It's done this way so that the current scopes do not affect those from the dependencies. We had an unsoundness when we used the scopes from the current session.oli-obk commentedon Oct 7, 2026
Right, but are the rmeta created by rustdoc or by rustc? Because if thr latter, and a no-op there, then why would rustdoc benefit from it being specified as documentation vs not being specified at all?
Urgau commentedon Oct 7, 2026
The later,
rustcis the one creating thermeta.When it said that is does nothing I meant that
rustcdoesn't condition on it (ie. rustc never checks if thedocumentationscope is active for a RealFilename, only rustdoc does that), butrustcstill encodes it inrmeta, otherwiserustdoccouldn't exploit it.Sorry for the confusion. Improved the wording in the top comment.
Urgau commentedon Oct 14, 2026
For information, #164279 moves the
documentationscope under theobjectalias scope. It currently covers themacro,debuginfoandcoveragescopes, and would include thedocumentationscope as well.Rational in #164279 (comment), but tl;dr is that it better reflects how the scope is actually used (for things that end up written to disk, which the
objectscope is meant to represent) and simplify things for Cargo.