Add a documentation remapping path scope for rustdoc usage

compiler/rustc_session/src/config.rs

@@ -1322,18 +1322,26 @@ impl OutputFilenames {
 pub(crate) fn parse_remap_path_scope(
     early_dcx: &EarlyDiagCtxt,
     matches: &getopts::Matches,
+    unstable_opts: &UnstableOptions,
 ) -> RemapPathScopeComponents {
     if let Some(v) = matches.opt_str("remap-path-scope") {
         let mut slot = RemapPathScopeComponents::empty();
         for s in v.split(',') {
             slot |= match s {
                 "macro" => RemapPathScopeComponents::MACRO,
                 "diagnostics" => RemapPathScopeComponents::DIAGNOSTICS,
+                "documentation" => {
+                    if !unstable_opts.unstable_options {
+                        early_dcx.early_fatal("remapping `documentation` path scope requested but `-Zunstable-options` not specified");
+                    }
+
+                    RemapPathScopeComponents::DOCUMENTATION
+                },
                 "debuginfo" => RemapPathScopeComponents::DEBUGINFO,
                 "coverage" => RemapPathScopeComponents::COVERAGE,
                 "object" => RemapPathScopeComponents::OBJECT,
                 "all" => RemapPathScopeComponents::all(),
-                _ => early_dcx.early_fatal("argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `debuginfo`, `coverage`, `object`, `all`"),
+                _ => early_dcx.early_fatal("argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`"),
             }
         }
         slot
@@ -2677,7 +2685,7 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
     let externs = parse_externs(early_dcx, matches, &unstable_opts);
 
     let remap_path_prefix = parse_remap_path_prefix(early_dcx, matches, &unstable_opts);
-    let remap_path_scope = parse_remap_path_scope(early_dcx, matches);
+    let remap_path_scope = parse_remap_path_scope(early_dcx, matches, &unstable_opts);
 
     let pretty = parse_pretty(early_dcx, &unstable_opts);
 

compiler/rustc_span/src/lib.rs

@@ -233,6 +233,8 @@ bitflags::bitflags! {
         const DEBUGINFO = 1 << 3;
         /// Apply remappings to coverage information
         const COVERAGE = 1 << 4;
+        /// Apply remappings to documentation information
+        const DOCUMENTATION = 1 << 5;
 
         /// An alias for `macro`, `debuginfo` and `coverage`. This ensures all paths in compiled
         /// executables, libraries and objects are remapped but not elsewhere.

src/doc/rustc/src/remap-source-paths.md

@@ -52,7 +52,7 @@ The valid scopes are:
 - `debuginfo` - apply remappings to debug information
 - `coverage` - apply remappings to coverage information
 - `object` - apply remappings to all paths in compiled executables or libraries, but not elsewhere. Currently an alias for `macro,coverage,debuginfo`.
-- `all` (default) - an alias for all of the above, also equivalent to supplying only `--remap-path-prefix` without `--remap-path-scope`.
+- `all` (default) - an alias for all of the above (and unstable scopes), also equivalent to supplying only `--remap-path-prefix` without `--remap-path-scope`.
 
 The scopes accepted by `--remap-path-scope` are not exhaustive - new scopes may be added in future releases for eventual stabilisation.
 This implies that the `all` scope can correspond to different scopes between releases.

src/doc/rustdoc/src/unstable-features.md

@@ -751,6 +751,22 @@ pass `--doctest-build-arg ARG` for each argument `ARG`.
 
 This flag enables the generation of toggles to expand macros in the HTML source code pages.
 
+## `--remap-path-prefix`: Remap source code paths in output
+
+This flag is the equivalent flag from `rustc` `--remap-path-prefix`.
+
+it permits remapping source path prefixes in all output, including compiler diagnostics,
+debug information, macro expansions, etc. It takes a value of the form `FROM=TO`
+where a path prefix equal to `FROM` is rewritten to the value `TO`.
+
+### `documentation` scope
+
+`rustdoc` (and by extension `rustc`) have a special `documentation` remapping scope, it
+permits remapping source paths that ends up in the generated documentation.
+
+Currently the scope can only be specified from `rustc`, due to the lack of an equivalent
+`--remap-path-scope` flag in `rustc`.
+
 ## `#[doc(cfg)]` and `#[doc(auto_cfg)]`
 
 This feature aims at providing rustdoc users the possibility to add visual markers to the rendered documentation to know under which conditions an item is available (currently possible through the following unstable feature: `doc_cfg`).

src/librustdoc/clean/types.rs

@@ -152,7 +152,7 @@ impl ExternalCrate {
             FileName::Real(ref p) => {
                 match p
                     .local_path()
-                    .or(Some(p.path(RemapPathScopeComponents::MACRO)))
+                    .or(Some(p.path(RemapPathScopeComponents::DOCUMENTATION)))
                     .unwrap()
                     .parent()
                 {

src/librustdoc/doctest.rs

@@ -957,8 +957,10 @@ impl ScrapedDocTest {
         if !item_path.is_empty() {
             item_path.push(' ');
         }
-        let name =
-            format!("{} - {item_path}(line {line})", filename.prefer_remapped_unconditionally());
+        let name = format!(
+            "{} - {item_path}(line {line})",
+            filename.display(RemapPathScopeComponents::DOCUMENTATION)
+        );
 
         Self { filename, line, langstr, text, name, span, global_crate_attrs }
     }
@@ -969,9 +971,12 @@ impl ScrapedDocTest {
     fn no_run(&self, opts: &RustdocOptions) -> bool {
         self.langstr.no_run || opts.no_run
     }
+
     fn path(&self) -> PathBuf {
         match &self.filename {
-            FileName::Real(name) => name.path(RemapPathScopeComponents::DIAGNOSTICS).to_path_buf(),
+            FileName::Real(name) => {
+                name.path(RemapPathScopeComponents::DOCUMENTATION).to_path_buf()
+            }
             _ => PathBuf::from(r"doctest.rs"),
         }
     }
@@ -1016,9 +1021,12 @@ impl CreateRunnableDocTests {
 
     fn add_test(&mut self, scraped_test: ScrapedDocTest, dcx: Option<DiagCtxtHandle<'_>>) {
         // For example `module/file.rs` would become `module_file_rs`
+        //
+        // Note that we are kind-of extending the definition of the MACRO scope here, but
+        // after all `#[doc]` is kind-of a macro.
         let file = scraped_test
             .filename
-            .prefer_local_unconditionally()
+            .display(RemapPathScopeComponents::MACRO)
             .to_string_lossy()
             .chars()
             .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })

src/librustdoc/doctest/extracted.rs

@@ -3,6 +3,7 @@
 //! This module contains the logic to extract doctests and output a JSON containing this
 //! information.
 
+use rustc_span::RemapPathScopeComponents;
 use rustc_span::edition::Edition;
 use serde::Serialize;
 
@@ -62,7 +63,7 @@ impl ExtractedDocTests {
             Some(&opts.crate_name),
         );
         self.doctests.push(ExtractedDocTest {
-            file: filename.prefer_remapped_unconditionally().to_string(),
+            file: filename.display(RemapPathScopeComponents::DOCUMENTATION).to_string(),
             line,
             doctest_attributes: langstr.into(),
             doctest_code: match wrapped {

src/librustdoc/html/render/context.rs

@@ -367,7 +367,7 @@ impl<'tcx> Context<'tcx> {
         let file = match span.filename(self.sess()) {
             FileName::Real(ref path) => path
                 .local_path()
-                .unwrap_or(path.path(RemapPathScopeComponents::MACRO))
+                .unwrap_or(path.path(RemapPathScopeComponents::DOCUMENTATION))
                 .to_path_buf(),
             _ => return None,
         };
@@ -503,7 +503,11 @@ impl<'tcx> Context<'tcx> {
 
         let src_root = match krate.src(tcx) {
             FileName::Real(ref p) => {
-                match p.local_path().unwrap_or(p.path(RemapPathScopeComponents::MACRO)).parent() {
+                match p
+                    .local_path()
+                    .unwrap_or(p.path(RemapPathScopeComponents::DOCUMENTATION))
+                    .parent()
+                {
                     Some(p) => p.to_path_buf(),
                     None => PathBuf::new(),
                 }

src/librustdoc/passes/calculate_doc_coverage.rs

@@ -124,7 +124,7 @@ impl CoverageCalculator<'_, '_> {
             &self
                 .items
                 .iter()
-                .map(|(k, v)| (k.prefer_local_unconditionally().to_string(), v))
+                .map(|(k, v)| (k.display(RemapPathScopeComponents::COVERAGE).to_string(), v))
                 .collect::<BTreeMap<String, &ItemCount>>(),
         )
         .expect("failed to convert JSON data to string")
@@ -168,9 +168,7 @@ impl CoverageCalculator<'_, '_> {
             if let Some(percentage) = count.percentage() {
                 print_table_record(
                     &limit_filename_len(
-                        file.display(RemapPathScopeComponents::DIAGNOSTICS)
-                            .to_string_lossy()
-                            .into(),
+                        file.display(RemapPathScopeComponents::COVERAGE).to_string(),
                     ),
                     count,
                     percentage,

tests/run-make/remap-path-prefix/rmake.rs

@@ -12,7 +12,9 @@ fn main() {
     let mut out_simple = rustc();
     let mut out_object = rustc();
     let mut out_macro = rustc();
+    let mut out_doc = rustc();
     let mut out_diagobj = rustc();
+    let mut out_diagdocobj = rustc();
     out_simple
         .remap_path_prefix("auxiliary", "/the/aux")
         .crate_type("lib")
@@ -28,23 +30,39 @@ fn main() {
         .crate_type("lib")
         .emit("metadata")
         .input("auxiliary/lib.rs");
+    out_doc
+        .remap_path_prefix("auxiliary", "/the/aux")
+        .crate_type("lib")
+        .emit("metadata")
+        .input("auxiliary/lib.rs");
     out_diagobj
         .remap_path_prefix("auxiliary", "/the/aux")
         .crate_type("lib")
         .emit("metadata")
         .input("auxiliary/lib.rs");
+    out_diagdocobj
+        .remap_path_prefix("auxiliary", "/the/aux")
+        .crate_type("lib")
+        .emit("metadata")
+        .input("auxiliary/lib.rs");
 
     out_simple.run();
     rmeta_contains("/the/aux/lib.rs");
     rmeta_not_contains("auxiliary");
 
     out_object.arg("--remap-path-scope=object");
     out_macro.arg("--remap-path-scope=macro");
+    out_doc.arg("--remap-path-scope=documentation").arg("-Zunstable-options");
     out_diagobj.arg("--remap-path-scope=diagnostics,object");
+    out_diagdocobj
+        .arg("--remap-path-scope=diagnostics,documentation,object")
+        .arg("-Zunstable-options");
     if is_darwin() {
         out_object.arg("-Csplit-debuginfo=off");
         out_macro.arg("-Csplit-debuginfo=off");
+        out_doc.arg("-Csplit-debuginfo=off");
         out_diagobj.arg("-Csplit-debuginfo=off");
+        out_diagdocobj.arg("-Csplit-debuginfo=off");
     }
 
     out_object.run();
@@ -53,8 +71,14 @@ fn main() {
     out_macro.run();
     rmeta_contains("/the/aux/lib.rs");
     rmeta_contains("auxiliary");
+    out_doc.run();
+    rmeta_contains("/the/aux/lib.rs");
+    rmeta_contains("auxiliary");
     out_diagobj.run();
     rmeta_contains("/the/aux/lib.rs");
+    rmeta_contains("auxiliary");
+    out_diagdocobj.run();
+    rmeta_contains("/the/aux/lib.rs");
     rmeta_not_contains("auxiliary");
 }
 

tests/ui/compile-flags/invalid/remap-path-scope.foo.stderr

@@ -0,0 +1,2 @@
+error: argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`
+

tests/ui/compile-flags/invalid/remap-path-scope.rs

@@ -0,0 +1,9 @@
+// Error on invalid --remap-path-scope arguments
+
+//@ revisions: foo underscore
+//@ [foo]compile-flags: --remap-path-scope=foo
+//@ [underscore]compile-flags: --remap-path-scope=macro_object
+
+//~? ERROR argument for `--remap-path-scope
+
+fn main() {}

tests/ui/compile-flags/invalid/remap-path-scope.underscore.stderr

@@ -0,0 +1,2 @@
+error: argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`
+

tests/ui/errors/auxiliary/file-doc.rs

@@ -0,0 +1,13 @@
+//@ compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@ compile-flags: --remap-path-scope=documentation -Zunstable-options
+
+#[macro_export]
+macro_rules! my_file {
+    () => {
+        file!()
+    };
+}
+
+pub fn file() -> &'static str {
+    file!()
+}

tests/ui/errors/auxiliary/trait-doc.rs

@@ -0,0 +1,4 @@
+//@ compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@ compile-flags: --remap-path-scope=documentation -Zunstable-options
+
+pub trait Trait: std::fmt::Display {}

tests/ui/errors/remap-path-prefix-diagnostics.only-doc-in-deps.stderr

@@ -0,0 +1,20 @@
+error[E0277]: `A` doesn't implement `std::fmt::Display`
+  --> $DIR/remap-path-prefix-diagnostics.rs:LL:COL
+   |
+LL | impl r#trait::Trait for A {}
+   |                         ^ unsatisfied trait bound
+   |
+help: the trait `std::fmt::Display` is not implemented for `A`
+  --> $DIR/remap-path-prefix-diagnostics.rs:LL:COL
+   |
+LL | struct A;
+   | ^^^^^^^^
+note: required by a bound in `Trait`
+  --> $DIR/auxiliary/trait-doc.rs:LL:COL
+   |
+LL | pub trait Trait: std::fmt::Display {}
+   |                  ^^^^^^^^^^^^^^^^^ required by this bound in `Trait`
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0277`.

tests/ui/errors/remap-path-prefix-diagnostics.rs

@@ -3,26 +3,30 @@
 // We test different combinations with/without remap in deps, with/without remap in this
 // crate but always in deps and always here but never in deps.
 
-//@ revisions: with-diag-in-deps with-macro-in-deps with-debuginfo-in-deps
-//@ revisions: only-diag-in-deps only-macro-in-deps only-debuginfo-in-deps
+//@ revisions: with-diag-in-deps with-macro-in-deps with-debuginfo-in-deps with-doc-in-deps
+//@ revisions: only-diag-in-deps only-macro-in-deps only-debuginfo-in-deps only-doc-in-deps
 //@ revisions: not-diag-in-deps
 
 //@[with-diag-in-deps] compile-flags: --remap-path-prefix={{src-base}}=remapped
 //@[with-macro-in-deps] compile-flags: --remap-path-prefix={{src-base}}=remapped
 //@[with-debuginfo-in-deps] compile-flags: --remap-path-prefix={{src-base}}=remapped
+//@[with-doc-in-deps] compile-flags: --remap-path-prefix={{src-base}}=remapped
 //@[not-diag-in-deps] compile-flags: --remap-path-prefix={{src-base}}=remapped
 
 //@[with-diag-in-deps] compile-flags: --remap-path-scope=diagnostics
 //@[with-macro-in-deps] compile-flags: --remap-path-scope=macro
 //@[with-debuginfo-in-deps] compile-flags: --remap-path-scope=debuginfo
+//@[with-doc-in-deps] compile-flags: --remap-path-scope=documentation -Zunstable-options
 //@[not-diag-in-deps] compile-flags: --remap-path-scope=diagnostics
 
 //@[with-diag-in-deps] aux-build:trait-diag.rs
 //@[with-macro-in-deps] aux-build:trait-macro.rs
 //@[with-debuginfo-in-deps] aux-build:trait-debuginfo.rs
+//@[with-doc-in-deps] aux-build:trait-doc.rs
 //@[only-diag-in-deps] aux-build:trait-diag.rs
 //@[only-macro-in-deps] aux-build:trait-macro.rs
 //@[only-debuginfo-in-deps] aux-build:trait-debuginfo.rs
+//@[only-doc-in-deps] aux-build:trait-doc.rs
 //@[not-diag-in-deps] aux-build:trait.rs
 
 // The $SRC_DIR*.rs:LL:COL normalisation doesn't kick in automatically
@@ -39,6 +43,9 @@ extern crate trait_macro as r#trait;
 #[cfg(any(with_debuginfo_in_deps, only_debuginfo_in_deps))]
 extern crate trait_debuginfo as r#trait;
 
+#[cfg(any(with_doc_in_deps, only_doc_in_deps))]
+extern crate trait_doc as r#trait;
+
 #[cfg(not_diag_in_deps)]
 extern crate r#trait as r#trait;
 
@@ -47,9 +54,11 @@ struct A;
 impl r#trait::Trait for A {}
 //[with-macro-in-deps]~^ ERROR `A` doesn't implement `std::fmt::Display`
 //[with-debuginfo-in-deps]~^^ ERROR `A` doesn't implement `std::fmt::Display`
-//[only-diag-in-deps]~^^^ ERROR `A` doesn't implement `std::fmt::Display`
-//[only-macro-in-deps]~^^^^ ERROR `A` doesn't implement `std::fmt::Display`
-//[only-debuginfo-in-deps]~^^^^^ ERROR `A` doesn't implement `std::fmt::Display`
+//[with-doc-in-deps]~^^^ ERROR `A` doesn't implement `std::fmt::Display`
+//[only-diag-in-deps]~^^^^ ERROR `A` doesn't implement `std::fmt::Display`
+//[only-macro-in-deps]~^^^^^ ERROR `A` doesn't implement `std::fmt::Display`
+//[only-debuginfo-in-deps]~^^^^^^ ERROR `A` doesn't implement `std::fmt::Display`
+//[only-doc-in-deps]~^^^^^^^ ERROR `A` doesn't implement `std::fmt::Display`
 
 //[with-diag-in-deps]~? ERROR `A` doesn't implement `std::fmt::Display`
 //[not-diag-in-deps]~? ERROR `A` doesn't implement `std::fmt::Display`

tests/ui/errors/remap-path-prefix-diagnostics.with-doc-in-deps.stderr

@@ -0,0 +1,20 @@
+error[E0277]: `A` doesn't implement `std::fmt::Display`
+  --> $DIR/remap-path-prefix-diagnostics.rs:LL:COL
+   |
+LL | impl r#trait::Trait for A {}
+   |                         ^ unsatisfied trait bound
+   |
+help: the trait `std::fmt::Display` is not implemented for `A`
+  --> $DIR/remap-path-prefix-diagnostics.rs:LL:COL
+   |
+LL | struct A;
+   | ^^^^^^^^
+note: required by a bound in `Trait`
+  --> $DIR/auxiliary/trait-doc.rs:LL:COL
+   |
+LL | pub trait Trait: std::fmt::Display {}
+   |                  ^^^^^^^^^^^^^^^^^ required by this bound in `Trait`
+
+error: aborting due to 1 previous error
+
+For more information about this error, try `rustc --explain E0277`.

tests/ui/errors/remap-path-prefix-macro.only-doc-in-deps.run.stdout

@@ -0,0 +1,3 @@
+file::my_file!() = $DIR/remap-path-prefix-macro.rs
+file::file() = $DIR/auxiliary/file-doc.rs
+file!() = $DIR/remap-path-prefix-macro.rs