Unrolled build for #151589

Rollup merge of #151589 - Urgau:documentation-scope, r=GuillaumeGomez

Add a `documentation` remapping path scope for rustdoc usage

This PR adds a new remapping path scope for rustdoc usage: `documentation`, instead of rustdoc abusing the other scopes for it's usage.

Like remapping paths in rustdoc, this scope is unstable. (rustdoc doesn't even have yet an equivalent to [rustc `--remap-path-scope`](https://doc.rust-lang.org/nightly/rustc/remap-source-paths.html#--remap-path-scope)).

I also took the opportunity to add a bit of documentation in rustdoc book.

Author: rust-timer

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");
 }