[rustdoc] Add new example disambiguator for intra-doc links

src/doc/rustdoc/src/scraped-examples.md

@@ -47,6 +47,24 @@ Rustdoc has a few techniques to ensure these examples don't overwhelm documentat
 
 For a given item, Rustdoc sorts its examples based on the size of the example — smaller ones are shown first.
 
+## Linking to an example source code
+
+You can use intra-doc links to link to a scraped example source file with `example@` disambiguator:
+
+```rust
+// If your example is named "foo":
+/// [example@foo]
+struct Item;
+```
+
+By default, the intra-doc link will link to the file containing the `main` function. If you want to
+link to another file, you can specify its path:
+
+```rust
+// If your example is named "foo":
+/// [example@foo/another_file.rs]
+struct Item;
+```
 
 ## FAQ
 

src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md

@@ -92,6 +92,9 @@ rendered as `Foo`. The following prefixes are available: `struct`, `enum`, `trai
 `mod`, `module`, `const`, `constant`, `fn`, `function`, `field`, `variant`, `method`, `derive`,
 `type`, `value`, `macro`, `prim` or `primitive`.
 
+There is another disambiguator available: `example`. If you want more information about this one,
+take a look at the [scraped examples chapter](../scraped-examples.md).
+
 You can also disambiguate for functions by adding `()` after the function name,
 or for macros by adding `!` after the macro name. The macro `!` can be followed by `()`, `{}`,
 or `[]`. Example:

src/etc/htmldocck.py

@@ -350,7 +350,7 @@ def resolve_path(self, path):
     def get_absolute_path(self, path):
         return os.path.join(self.root, path)
 
-    def get_file(self, path):
+    def get_file(self, path, need_content):
         path = self.resolve_path(path)
         if path in self.files:
             return self.files[path]
@@ -359,6 +359,9 @@ def get_file(self, path):
         if not(os.path.exists(abspath) and os.path.isfile(abspath)):
             raise FailedCheck('File does not exist {!r}'.format(path))
 
+        if not need_content:
+            return None
+
         with io.open(abspath, encoding='utf-8') as f:
             data = f.read()
             self.files[path] = data
@@ -614,15 +617,15 @@ def check_command(c, cache):
             # has <path> = file existence
             if len(c.args) == 1 and not regexp and 'raw' not in c.cmd:
                 try:
-                    cache.get_file(c.args[0])
+                    cache.get_file(c.args[0], False)
                     ret = True
                 except FailedCheck as err:
                     cerr = str(err)
                     ret = False
             # hasraw/matchesraw <path> <pat> = string test
             elif len(c.args) == 2 and 'raw' in c.cmd:
                 cerr = "`PATTERN` did not match"
-                ret = check_string(cache.get_file(c.args[0]), c.args[1], regexp)
+                ret = check_string(cache.get_file(c.args[0], True), c.args[1], regexp)
             # has/matches <path> <pat> <match> = XML tree test
             elif len(c.args) == 3 and 'raw' not in c.cmd:
                 cerr = "`XPATH PATTERN` did not match"

src/librustdoc/clean/types.rs

@@ -487,21 +487,38 @@ impl Item {
         let Some(links) = cx.cache().intra_doc_links.get(&self.item_id) else { return vec![] };
         links
             .iter()
-            .filter_map(|ItemLink { link: s, link_text, page_id: id, ref fragment }| {
-                debug!(?id);
-                if let Ok((mut href, ..)) = href(*id, cx) {
-                    debug!(?href);
-                    if let Some(ref fragment) = *fragment {
-                        fragment.render(&mut href, cx.tcx())
+            .filter_map(|ItemLink { link: s, link_text, ref kind, ref fragment }| match kind {
+                ItemLinkKind::Item { page_id: id } => {
+                    debug!(?id);
+                    if let Some(id) = id {
+                        if let Ok((mut href, ..)) = href(*id, cx) {
+                            debug!(?href);
+                            if let Some(ref fragment) = *fragment {
+                                fragment.render(&mut href, cx.tcx())
+                            }
+                            return Some(RenderedLink {
+                                original_text: s.clone(),
+                                new_text: link_text.clone(),
+                                tooltip: link_tooltip(*id, fragment, cx),
+                                href,
+                            });
+                        }
                     }
+                    None
+                }
+                ItemLinkKind::Example { file_path } => {
+                    let example_name = file_path.split('/').next().unwrap_or(file_path);
+                    let mut href =
+                        std::iter::repeat("../").take(cx.current.len()).collect::<String>();
+                    href.push_str("src/");
+                    href.push_str(file_path);
+                    href.push_str(".html");
                     Some(RenderedLink {
                         original_text: s.clone(),
                         new_text: link_text.clone(),
-                        tooltip: link_tooltip(*id, fragment, cx),
+                        tooltip: format!("Example {example_name}"),
                         href,
                     })
-                } else {
-                    None
                 }
             })
             .collect()
@@ -1110,6 +1127,23 @@ impl<I: Iterator<Item = ast::MetaItemInner>> NestedAttributesExt for I {
     }
 }
 
+/// The kind of a link that has not yet been rendered.
+///
+/// It is used in [`ItemLink`].
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub(crate) enum ItemLinkKind {
+    Item {
+        /// The `DefId` of the Item whose **HTML Page** contains the item being
+        /// linked to. This will be different to `item_id` on item's that don't
+        /// have their own page, such as struct fields and enum variants.
+        page_id: Option<DefId>,
+    },
+    Example {
+        /// The path of the example file.
+        file_path: String,
+    },
+}
+
 /// A link that has not yet been rendered.
 ///
 /// This link will be turned into a rendered link by [`Item::links`].
@@ -1122,12 +1156,9 @@ pub(crate) struct ItemLink {
     /// This may not be the same as `link` if there was a disambiguator
     /// in an intra-doc link (e.g. \[`fn@f`\])
     pub(crate) link_text: Box<str>,
-    /// The `DefId` of the Item whose **HTML Page** contains the item being
-    /// linked to. This will be different to `item_id` on item's that don't
-    /// have their own page, such as struct fields and enum variants.
-    pub(crate) page_id: DefId,
     /// The url fragment to append to the link
     pub(crate) fragment: Option<UrlFragment>,
+    pub(crate) kind: ItemLinkKind,
 }
 
 pub struct RenderedLink {

src/librustdoc/config.rs

@@ -25,7 +25,7 @@ use crate::html::markdown::IdMap;
 use crate::html::render::StylePath;
 use crate::html::static_files;
 use crate::passes::{self, Condition};
-use crate::scrape_examples::{AllCallLocations, ScrapeExamplesOptions};
+use crate::scrape_examples::{AllCallLocations, AllExampleFiles, ScrapeExamplesOptions};
 use crate::{html, opts, theme};
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
@@ -287,6 +287,8 @@ pub(crate) struct RenderOptions {
     pub(crate) generate_link_to_definition: bool,
     /// Set of function-call locations to include as examples
     pub(crate) call_locations: AllCallLocations,
+    /// Set of function-call locations to include as examples
+    pub(crate) examples_files: AllExampleFiles,
     /// If `true`, Context::init will not emit shared files.
     pub(crate) no_emit_shared: bool,
     /// If `true`, HTML source code pages won't be generated.
@@ -773,7 +775,8 @@ impl Options {
 
         let scrape_examples_options = ScrapeExamplesOptions::new(matches, dcx);
         let with_examples = matches.opt_strs("with-examples");
-        let call_locations = crate::scrape_examples::load_call_locations(with_examples, dcx);
+        let (call_locations, examples_files) =
+            crate::scrape_examples::load_call_locations(with_examples, dcx);
 
         let unstable_features =
             rustc_feature::UnstableFeatures::from_environment(crate_name.as_deref());
@@ -846,6 +849,7 @@ impl Options {
             emit,
             generate_link_to_definition,
             call_locations,
+            examples_files,
             no_emit_shared: false,
             html_no_source,
             output_to_stdout,

src/librustdoc/html/render/context.rs

@@ -132,6 +132,8 @@ pub(crate) struct SharedContext<'tcx> {
     /// Controls whether we read / write to cci files in the doc root. Defaults read=true,
     /// write=true
     should_merge: ShouldMerge,
+    /// Paths of generated files.
+    pub(crate) emitted_local_sources: RefCell<FxIndexSet<String>>,
 }
 
 impl SharedContext<'_> {
@@ -554,6 +556,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
             cache,
             call_locations,
             should_merge: options.should_merge,
+            emitted_local_sources: Default::default(),
         };
 
         let dst = output;

src/librustdoc/html/sources.rs

@@ -30,7 +30,7 @@ pub(crate) fn render(cx: &mut Context<'_>, krate: &clean::Crate) -> Result<(), E
     let crate_name = crate_name.as_str();
 
     let mut collector =
-        SourceCollector { dst, cx, emitted_local_sources: FxHashSet::default(), crate_name };
+        SourceCollector { dst, cx, crate_name, emitted_paths: FxHashSet::default() };
     collector.visit_crate(krate);
     Ok(())
 }
@@ -117,9 +117,10 @@ struct SourceCollector<'a, 'tcx> {
 
     /// Root destination to place all HTML output into
     dst: PathBuf,
-    emitted_local_sources: FxHashSet<PathBuf>,
 
     crate_name: &'a str,
+
+    emitted_paths: FxHashSet<PathBuf>,
 }
 
 impl DocVisitor<'_> for SourceCollector<'_, '_> {
@@ -182,7 +183,7 @@ impl SourceCollector<'_, '_> {
             }
             _ => return Ok(()),
         };
-        if self.emitted_local_sources.contains(&*p) {
+        if self.emitted_paths.contains(&*p) {
             // We've already emitted this source
             return Ok(());
         }
@@ -245,6 +246,7 @@ impl SourceCollector<'_, '_> {
             resource_suffix: &shared.resource_suffix,
             rust_logo: has_doc_flag(self.cx.tcx(), LOCAL_CRATE.as_def_id(), sym::rust_logo),
         };
+        let file_path_s = file_path.display().to_string();
         let v = layout::render(
             &shared.layout,
             &page,
@@ -264,7 +266,8 @@ impl SourceCollector<'_, '_> {
             &shared.style_files,
         );
         shared.fs.write(cur, v)?;
-        self.emitted_local_sources.insert(p);
+        self.emitted_paths.insert(p);
+        self.cx.shared.emitted_local_sources.borrow_mut().insert(file_path_s);
         Ok(())
     }
 }

src/librustdoc/json/conversions.rs

@@ -15,7 +15,7 @@ use rustc_span::{Pos, Symbol, sym};
 use rustdoc_json_types::*;
 
 use super::FullItemId;
-use crate::clean::{self, ItemId};
+use crate::clean::{self, ItemId, ItemLink, ItemLinkKind};
 use crate::formats::FormatRenderer;
 use crate::formats::item_type::ItemType;
 use crate::json::JsonRenderer;
@@ -30,14 +30,20 @@ impl JsonRenderer<'_> {
             .get(&item.item_id)
             .into_iter()
             .flatten()
-            .map(|clean::ItemLink { link, page_id, fragment, .. }| {
-                let id = match fragment {
-                    Some(UrlFragment::Item(frag_id)) => *frag_id,
-                    // FIXME: Pass the `UserWritten` segment to JSON consumer.
-                    Some(UrlFragment::UserWritten(_)) | None => *page_id,
-                };
-
-                (String::from(&**link), self.id_from_item_default(id.into()))
+            .filter_map(|ItemLink { link, kind, fragment, .. }| {
+                if let ItemLinkKind::Item { page_id } = kind
+                    && let Some(page_id) = page_id
+                {
+                    let id = match fragment {
+                        Some(UrlFragment::Item(frag_id)) => *frag_id,
+                        // FIXME: Pass the `UserWritten` segment to JSON consumer.
+                        Some(UrlFragment::UserWritten(_)) | None => *page_id,
+                    };
+
+                    Some((String::from(&**link), self.id_from_item_default(id.into())))
+                } else {
+                    None
+                }
             })
             .collect();
         let docs = item.opt_doc_value();