\
\
",
root_path = cx.root_path(),
id = id
)?;
// Create a URL to a particular location in a reverse-dependency's source file
let link_to_loc = |call_data: &CallData, loc: &CallLocation| -> (String, String) {
let (line_lo, line_hi) = loc.call_expr.line_span;
let (anchor, title) = if line_lo == line_hi {
((line_lo + 1).to_string(), format!("line {}", line_lo + 1))
} else {
(
format!("{}-{}", line_lo + 1, line_hi + 1),
format!("lines {}-{}", line_lo + 1, line_hi + 1),
)
};
let url = format!("{}{}#{anchor}", cx.root_path(), call_data.url);
(url, title)
};
// Generate the HTML for a single example, being the title and code block
let write_example = |w: &mut W, (path, call_data): (&PathBuf, &CallData)| -> bool {
let contents = match fs::read_to_string(path) {
Ok(contents) => contents,
Err(err) => {
let span = item.span(tcx).map_or(DUMMY_SP, |span| span.inner());
tcx.dcx().span_err(span, format!("failed to read file {}: {err}", path.display()));
return false;
}
};
// To reduce file sizes, we only want to embed the source code needed to understand the example, not
// the entire file. So we find the smallest byte range that covers all items enclosing examples.
assert!(!call_data.locations.is_empty());
let min_loc =
call_data.locations.iter().min_by_key(|loc| loc.enclosing_item.byte_span.0).unwrap();
let byte_min = min_loc.enclosing_item.byte_span.0;
let line_min = min_loc.enclosing_item.line_span.0;
let max_loc =
call_data.locations.iter().max_by_key(|loc| loc.enclosing_item.byte_span.1).unwrap();
let byte_max = max_loc.enclosing_item.byte_span.1;
let line_max = max_loc.enclosing_item.line_span.1;
// The output code is limited to that byte range.
let contents_subset = &contents[(byte_min as usize)..(byte_max as usize)];
// The call locations need to be updated to reflect that the size of the program has changed.
// Specifically, the ranges are all subtracted by `byte_min` since that's the new zero point.
let (mut byte_ranges, line_ranges): (Vec<_>, Vec<_>) = call_data
.locations
.iter()
.map(|loc| {
let (byte_lo, byte_hi) = loc.call_ident.byte_span;
let (line_lo, line_hi) = loc.call_expr.line_span;
let byte_range = (byte_lo - byte_min, byte_hi - byte_min);
let line_range = (line_lo - line_min, line_hi - line_min);
let (line_url, line_title) = link_to_loc(call_data, loc);
(byte_range, (line_range, line_url, line_title))
})
.unzip();
let (_, init_url, init_title) = &line_ranges[0];
let needs_expansion = line_max - line_min > NUM_VISIBLE_LINES;
let locations_encoded = serde_json::to_string(&line_ranges).unwrap();
let source_map = tcx.sess.source_map();
let files = source_map.files();
let local = tcx.sess.local_crate_source_file().unwrap();
let get_file_start_pos = || {
let crate_src = local.clone().into_local_path()?;
let abs_crate_src = crate_src.canonicalize().ok()?;
let crate_root = abs_crate_src.parent()?.parent()?;
let rel_path = path.strip_prefix(crate_root).ok()?;
files
.iter()
.find(|file| match &file.name {
FileName::Real(RealFileName::LocalPath(other_path)) => rel_path == other_path,
_ => false,
})
.map(|file| file.start_pos)
};
// Look for the example file in the source map if it exists, otherwise
// return a span to the local crate's source file
let Some(file_span) = get_file_start_pos()
.or_else(|| {
files
.iter()
.find(|file| match &file.name {
FileName::Real(file_name) => file_name == &local,
_ => false,
})
.map(|file| file.start_pos)
})
.map(|start_pos| {
rustc_span::Span::with_root_ctxt(
start_pos + BytePos(byte_min),
start_pos + BytePos(byte_max),
)
})
else {
// if the fallback span can't be built, don't render the code for this example
return false;
};
let mut decoration_info = FxIndexMap::default();
decoration_info.insert("highlight focus", vec![byte_ranges.remove(0)]);
decoration_info.insert("highlight", byte_ranges);
sources::print_src(
w,
contents_subset,
file_span,
cx,
&cx.root_path(),
&highlight::DecorationInfo(decoration_info),
&sources::SourceContext::Embedded(sources::ScrapedInfo {
needs_expansion,
offset: line_min,
name: &call_data.display_name,
url: init_url,
title: init_title,
locations: locations_encoded,
}),
)
.unwrap();
true
};
// The call locations are output in sequence, so that sequence needs to be determined.
// Ideally the most "relevant" examples would be shown first, but there's no general algorithm
// for determining relevance. We instead proxy relevance with the following heuristics:
// 1. Code written to be an example is better than code not written to be an example, e.g.
// a snippet from examples/foo.rs is better than src/lib.rs. We don't know the Cargo
// directory structure in Rustdoc, so we proxy this by prioritizing code that comes from
// a --crate-type bin.
// 2. Smaller examples are better than large examples. So we prioritize snippets that have
// the smallest number of lines in their enclosing item.
// 3. Finally we sort by the displayed file name, which is arbitrary but prevents the
// ordering of examples from randomly changing between Rustdoc invocations.
let ordered_locations = {
fn sort_criterion<'a>(
(_, call_data): &(&PathBuf, &'a CallData),
) -> (bool, u32, &'a String) {
// Use the first location because that's what the user will see initially
let (lo, hi) = call_data.locations[0].enclosing_item.byte_span;
(!call_data.is_bin, hi - lo, &call_data.display_name)
}
let mut locs = call_locations.iter().collect::
>();
locs.sort_by_key(sort_criterion);
locs
};
let mut it = ordered_locations.into_iter().peekable();
// An example may fail to write if its source can't be read for some reason, so this method
// continues iterating until a write succeeds
let write_and_skip_failure = |w: &mut W, it: &mut Peekable<_>| {
for example in it.by_ref() {
if write_example(&mut *w, example) {
break;
}
}
};
// Write just one example that's visible by default in the method's description.
write_and_skip_failure(&mut w, &mut it);
// Then add the remaining examples in a hidden section.
if it.peek().is_some() {
write!(
w,
"\
\
More examples\
\
Hide additional examples
\
\
"
)?;
// Only generate inline code for MAX_FULL_EXAMPLES number of examples. Otherwise we could
// make the page arbitrarily huge!
for _ in 0..MAX_FULL_EXAMPLES {
write_and_skip_failure(&mut w, &mut it);
}
// For the remaining examples, generate a
")?;
}
w.write_str("