diff options
Diffstat (limited to 'src/librustdoc/html/render/mod.rs')
| -rw-r--r-- | src/librustdoc/html/render/mod.rs | 389 |
1 files changed, 341 insertions, 48 deletions
diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index dc5aec3b084..a1b86c87d3a 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -40,24 +40,29 @@ crate use span_map::{collect_spans_and_sources, LinkFromSrc}; use std::collections::VecDeque; use std::default::Default; use std::fmt; +use std::fs; +use std::iter::Peekable; use std::path::PathBuf; use std::str; use std::string::ToString; use rustc_ast_pretty::pprust; use rustc_attr::{ConstStability, Deprecation, StabilityLevel}; -use rustc_data_structures::fx::FxHashSet; +use rustc_data_structures::fx::{FxHashMap, FxHashSet}; use rustc_hir as hir; use rustc_hir::def::CtorKind; use rustc_hir::def_id::DefId; use rustc_hir::Mutability; use rustc_middle::middle::stability; use rustc_middle::ty::TyCtxt; -use rustc_span::symbol::{kw, sym, Symbol}; +use rustc_span::{ + symbol::{kw, sym, Symbol}, + BytePos, FileName, RealFileName, +}; use serde::ser::SerializeSeq; use serde::{Serialize, Serializer}; -use crate::clean::{self, GetDefId, ItemId, RenderedLink, SelfTy}; +use crate::clean::{self, ItemId, RenderedLink, SelfTy}; use crate::docfs::PathError; use crate::error::Error; use crate::formats::cache::Cache; @@ -68,7 +73,10 @@ use crate::html::format::{ href, print_abi_with_space, print_constness_with_space, print_default_space, print_generic_bounds, print_where_clause, Buffer, HrefError, PrintWithSpace, }; +use crate::html::highlight; use crate::html::markdown::{HeadingOffset, Markdown, MarkdownHtml, MarkdownSummaryLine}; +use crate::html::sources; +use crate::scrape_examples::CallData; /// A pair of name and its optional document. crate type NameDoc = (String, Option<String>); @@ -118,8 +126,8 @@ impl Serialize for IndexItemFunctionType { // If we couldn't figure out a type, just write `null`. let mut iter = self.inputs.iter(); if match self.output { - Some(ref output) => iter.chain(output.iter()).any(|ref i| i.ty.name.is_none()), - None => iter.any(|ref i| i.ty.name.is_none()), + Some(ref output) => iter.chain(output.iter()).any(|i| i.ty.name.is_none()), + None => iter.any(|i| i.ty.name.is_none()), } { serializer.serialize_none() } else { @@ -585,6 +593,14 @@ fn document_full_inner( render_markdown(w, cx, &s, item.links(cx), heading_offset); } } + + let kind = match &*item.kind { + clean::ItemKind::StrippedItem(box kind) | kind => kind, + }; + + if let clean::ItemKind::FunctionItem(..) | clean::ItemKind::MethodItem(..) = kind { + render_call_locations(w, cx, item); + } } /// Add extra information about an item such as: @@ -890,7 +906,7 @@ fn render_assoc_item( AssocItemLink::GotoSource(did, provided_methods) => { // We're creating a link from an impl-item to the corresponding // trait-item and need to map the anchored type accordingly. - let ty = if provided_methods.contains(&name) { + let ty = if provided_methods.contains(name) { ItemType::Method } else { ItemType::TyMethod @@ -949,7 +965,7 @@ fn render_assoc_item( name = name, generics = g.print(cx), decl = d.full_print(header_len, indent, header.asyncness, cx), - notable_traits = notable_traits_decl(&d, cx), + notable_traits = notable_traits_decl(d, cx), where_clause = print_where_clause(g, cx, indent, end_newline), ) } @@ -992,7 +1008,7 @@ fn attributes(it: &clean::Item) -> Vec<String> { .iter() .filter_map(|attr| { if ALLOWED_ATTRIBUTES.contains(&attr.name_or_empty()) { - Some(pprust::attribute_to_string(&attr).replace("\n", "").replace(" ", " ")) + Some(pprust::attribute_to_string(attr).replace("\n", "").replace(" ", " ")) } else { None } @@ -1025,7 +1041,7 @@ enum AssocItemLink<'a> { impl<'a> AssocItemLink<'a> { fn anchor(&self, id: &'a str) -> Self { match *self { - AssocItemLink::Anchor(_) => AssocItemLink::Anchor(Some(&id)), + AssocItemLink::Anchor(_) => AssocItemLink::Anchor(Some(id)), ref other => *other, } } @@ -1104,7 +1120,7 @@ fn render_assoc_items( let (blanket_impl, concrete): (Vec<&&Impl>, _) = concrete.into_iter().partition(|t| t.inner_impl().blanket_impl.is_some()); - let mut impls = Buffer::empty_from(&w); + let mut impls = Buffer::empty_from(w); render_impls(cx, &mut impls, &concrete, containing_item); let impls = impls.into_inner(); if !impls.is_empty() { @@ -1168,8 +1184,8 @@ fn render_deref_methods( debug!("Render deref methods for {:#?}, target {:#?}", impl_.inner_impl().for_, target); let what = AssocItemRender::DerefFor { trait_: deref_type, type_: real_target, deref_mut_: deref_mut }; - if let Some(did) = target.def_id_full(cache) { - if let Some(type_did) = impl_.inner_impl().for_.def_id_full(cache) { + if let Some(did) = target.def_id(cache) { + if let Some(type_did) = impl_.inner_impl().for_.def_id(cache) { // `impl Deref<Target = S> for S` if did == type_did { // Avoid infinite cycles @@ -1215,7 +1231,7 @@ fn should_render_item(item: &clean::Item, deref_mut_: bool, tcx: TyCtxt<'_>) -> fn notable_traits_decl(decl: &clean::FnDecl, cx: &Context<'_>) -> String { let mut out = Buffer::html(); - if let Some(did) = decl.output.def_id_full(cx.cache()) { + if let Some(did) = decl.output.as_return().and_then(|t| t.def_id(cx.cache())) { if let Some(impls) = cx.cache().impls.get(&did) { for i in impls { let impl_ = i.inner_impl(); @@ -1317,7 +1333,7 @@ fn render_impl( && match render_mode { RenderMode::Normal => true, RenderMode::ForDeref { mut_: deref_mut_ } => { - should_render_item(&item, deref_mut_, cx.tcx()) + should_render_item(item, deref_mut_, cx.tcx()) } }; @@ -1550,7 +1566,7 @@ fn render_impl( &mut impl_items, cx, &t.trait_, - &i.inner_impl(), + i.inner_impl(), &i.impl_item, parent, render_mode, @@ -1811,23 +1827,53 @@ fn get_next_url(used_links: &mut FxHashSet<String>, url: String) -> String { format!("{}-{}", url, add) } +struct SidebarLink { + name: Symbol, + url: String, +} + +impl fmt::Display for SidebarLink { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "<a href=\"#{}\">{}</a>", self.url, self.name) + } +} + +impl PartialEq for SidebarLink { + fn eq(&self, other: &Self) -> bool { + self.url == other.url + } +} + +impl Eq for SidebarLink {} + +impl PartialOrd for SidebarLink { + fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> { + Some(self.cmp(other)) + } +} + +impl Ord for SidebarLink { + fn cmp(&self, other: &Self) -> std::cmp::Ordering { + self.url.cmp(&other.url) + } +} + fn get_methods( i: &clean::Impl, for_deref: bool, used_links: &mut FxHashSet<String>, deref_mut: bool, tcx: TyCtxt<'_>, -) -> Vec<String> { +) -> Vec<SidebarLink> { i.items .iter() .filter_map(|item| match item.name { - Some(ref name) if !name.is_empty() && item.is_method() => { + Some(name) if !name.is_empty() && item.is_method() => { if !for_deref || should_render_item(item, deref_mut, tcx) { - Some(format!( - "<a href=\"#{}\">{}</a>", - get_next_url(used_links, format!("method.{}", name)), - name - )) + Some(SidebarLink { + name, + url: get_next_url(used_links, format!("method.{}", name)), + }) } else { None } @@ -1837,6 +1883,22 @@ fn get_methods( .collect::<Vec<_>>() } +fn get_associated_constants( + i: &clean::Impl, + used_links: &mut FxHashSet<String>, +) -> Vec<SidebarLink> { + i.items + .iter() + .filter_map(|item| match item.name { + Some(name) if !name.is_empty() && item.is_associated_const() => Some(SidebarLink { + name, + url: get_next_url(used_links, format!("associatedconstant.{}", name)), + }), + _ => None, + }) + .collect::<Vec<_>>() +} + // The point is to url encode any potential character from a type with genericity. fn small_url_encode(s: String) -> String { let mut st = String::new(); @@ -1881,23 +1943,40 @@ fn sidebar_assoc_items(cx: &Context<'_>, out: &mut Buffer, it: &clean::Item) { { let used_links_bor = &mut used_links; - let mut ret = v + let mut assoc_consts = v + .iter() + .flat_map(|i| get_associated_constants(i.inner_impl(), used_links_bor)) + .collect::<Vec<_>>(); + if !assoc_consts.is_empty() { + // We want links' order to be reproducible so we don't use unstable sort. + assoc_consts.sort(); + + out.push_str( + "<h3 class=\"sidebar-title\">\ + <a href=\"#implementations\">Associated Constants</a>\ + </h3>\ + <div class=\"sidebar-links\">", + ); + for line in assoc_consts { + write!(out, "{}", line); + } + out.push_str("</div>"); + } + let mut methods = v .iter() .filter(|i| i.inner_impl().trait_.is_none()) - .flat_map(move |i| { - get_methods(i.inner_impl(), false, used_links_bor, false, cx.tcx()) - }) + .flat_map(|i| get_methods(i.inner_impl(), false, used_links_bor, false, cx.tcx())) .collect::<Vec<_>>(); - if !ret.is_empty() { + if !methods.is_empty() { // We want links' order to be reproducible so we don't use unstable sort. - ret.sort(); + methods.sort(); out.push_str( "<h3 class=\"sidebar-title\"><a href=\"#implementations\">Methods</a></h3>\ <div class=\"sidebar-links\">", ); - for line in ret { - out.push_str(&line); + for line in methods { + write!(out, "{}", line); } out.push_str("</div>"); } @@ -1981,7 +2060,7 @@ fn sidebar_assoc_items(cx: &Context<'_>, out: &mut Buffer, it: &clean::Item) { } } -fn sidebar_deref_methods(cx: &Context<'_>, out: &mut Buffer, impl_: &Impl, v: &Vec<Impl>) { +fn sidebar_deref_methods(cx: &Context<'_>, out: &mut Buffer, impl_: &Impl, v: &[Impl]) { let c = cx.cache(); debug!("found Deref: {:?}", impl_); @@ -1995,8 +2074,8 @@ fn sidebar_deref_methods(cx: &Context<'_>, out: &mut Buffer, impl_: &Impl, v: &V }) { debug!("found target, real_target: {:?} {:?}", target, real_target); - if let Some(did) = target.def_id_full(c) { - if let Some(type_did) = impl_.inner_impl().for_.def_id_full(c) { + if let Some(did) = target.def_id(c) { + if let Some(type_did) = impl_.inner_impl().for_.def_id(c) { // `impl Deref<Target = S> for S` if did == type_did { // Avoid infinite cycles @@ -2006,7 +2085,7 @@ fn sidebar_deref_methods(cx: &Context<'_>, out: &mut Buffer, impl_: &Impl, v: &V } let deref_mut = v.iter().any(|i| i.trait_did() == cx.tcx().lang_items().deref_mut_trait()); let inner_impl = target - .def_id_full(c) + .def_id(c) .or_else(|| { target.primitive_type().and_then(|prim| c.primitive_locations.get(&prim).cloned()) }) @@ -2032,7 +2111,7 @@ fn sidebar_deref_methods(cx: &Context<'_>, out: &mut Buffer, impl_: &Impl, v: &V ret.sort(); out.push_str("<div class=\"sidebar-links\">"); for link in ret { - out.push_str(&link); + write!(out, "{}", link); } out.push_str("</div>"); } @@ -2080,16 +2159,14 @@ fn get_id_for_impl_on_foreign_type( fn extract_for_impl_name(item: &clean::Item, cx: &Context<'_>) -> Option<(String, String)> { match *item.kind { clean::ItemKind::ImplItem(ref i) => { - if let Some(ref trait_) = i.trait_ { + i.trait_.as_ref().map(|trait_| { // Alternative format produces no URLs, // so this parameter does nothing. - Some(( + ( format!("{:#}", i.for_.print(cx)), get_id_for_impl_on_foreign_type(&i.for_, trait_, cx), - )) - } else { - None - } + ) + }) } _ => None, } @@ -2169,10 +2246,7 @@ fn sidebar_trait(cx: &Context<'_>, buf: &mut Buffer, it: &clean::Item, t: &clean let mut res = implementors .iter() .filter(|i| { - i.inner_impl() - .for_ - .def_id_full(cache) - .map_or(false, |d| !cache.paths.contains_key(&d)) + i.inner_impl().for_.def_id(cache).map_or(false, |d| !cache.paths.contains_key(&d)) }) .filter_map(|i| extract_for_impl_name(&i.impl_item, cx)) .collect::<Vec<_>>(); @@ -2264,9 +2338,10 @@ fn sidebar_enum(cx: &Context<'_>, buf: &mut Buffer, it: &clean::Item, e: &clean: let mut variants = e .variants .iter() - .filter_map(|v| match v.name { - Some(ref name) => Some(format!("<a href=\"#variant.{name}\">{name}</a>", name = name)), - _ => None, + .filter_map(|v| { + v.name + .as_ref() + .map(|name| format!("<a href=\"#variant.{name}\">{name}</a>", name = name)) }) .collect::<Vec<_>>(); if !variants.is_empty() { @@ -2427,3 +2502,221 @@ fn collect_paths_for_type(first_ty: clean::Type, cache: &Cache) -> Vec<String> { } out } + +const MAX_FULL_EXAMPLES: usize = 5; +const NUM_VISIBLE_LINES: usize = 10; + +/// Generates the HTML for example call locations generated via the --scrape-examples flag. +fn render_call_locations(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item) { + let tcx = cx.tcx(); + let def_id = item.def_id.expect_def_id(); + let key = tcx.def_path_hash(def_id); + let call_locations = match cx.shared.call_locations.get(&key) { + Some(call_locations) => call_locations, + _ => { + return; + } + }; + + // Generate a unique ID so users can link to this section for a given method + let id = cx.id_map.borrow_mut().derive("scraped-examples"); + write!( + w, + "<div class=\"docblock scraped-example-list\">\ + <span></span>\ + <h5 id=\"{id}\" class=\"section-header\">\ + <a href=\"#{id}\">Examples found in repository</a>\ + </h5>", + id = id + ); + + // Generate the HTML for a single example, being the title and code block + let write_example = |w: &mut Buffer, (path, call_data): (&PathBuf, &CallData)| -> bool { + let contents = match fs::read_to_string(&path) { + Ok(contents) => contents, + Err(err) => { + let span = item.span(tcx).inner(); + tcx.sess + .span_err(span, &format!("failed to read file {}: {}", path.display(), err)); + 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_expr.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 (anchor, line_title) = if line_lo == line_hi { + (format!("{}", line_lo + 1), format!("line {}", line_lo + 1)) + } else { + ( + format!("{}-{}", line_lo + 1, line_hi + 1), + format!("lines {}-{}", line_lo + 1, line_hi + 1), + ) + }; + let line_url = format!("{}{}#{}", cx.root_path(), call_data.url, anchor); + + (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(); + + write!( + w, + "<div class=\"scraped-example {expanded_cls}\" data-locs=\"{locations}\">\ + <div class=\"scraped-example-title\">\ + {name} (<a href=\"{url}\">{title}</a>)\ + </div>\ + <div class=\"code-wrapper\">", + expanded_cls = if needs_expansion { "" } else { "expanded" }, + name = call_data.display_name, + url = init_url, + title = init_title, + // The locations are encoded as a data attribute, so they can be read + // later by the JS for interactions. + locations = Escape(&locations_encoded) + ); + + if line_ranges.len() > 1 { + write!(w, r#"<span class="prev">≺</span> <span class="next">≻</span>"#); + } + + if needs_expansion { + write!(w, r#"<span class="expand">↕</span>"#); + } + + // Look for the example file in the source map if it exists, otherwise return a dummy span + let file_span = (|| { + let source_map = tcx.sess.source_map(); + let crate_src = tcx.sess.local_crate_source_file.as_ref()?; + 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()?; + let files = source_map.files(); + let file = files.iter().find(|file| match &file.name { + FileName::Real(RealFileName::LocalPath(other_path)) => rel_path == other_path, + _ => false, + })?; + Some(rustc_span::Span::with_root_ctxt( + file.start_pos + BytePos(byte_min), + file.start_pos + BytePos(byte_max), + )) + })() + .unwrap_or(rustc_span::DUMMY_SP); + + // The root path is the inverse of Context::current + let root_path = vec!["../"; cx.current.len() - 1].join(""); + + let mut decoration_info = FxHashMap::default(); + decoration_info.insert("highlight focus", vec![byte_ranges.remove(0)]); + decoration_info.insert("highlight", byte_ranges); + + sources::print_src( + w, + contents_subset, + call_data.edition, + file_span, + cx, + &root_path, + Some(highlight::DecorationInfo(decoration_info)), + sources::SourceContext::Embedded { offset: line_min }, + ); + write!(w, "</div></div>"); + + 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. Instead, we prefer the smallest examples being likely the easiest to + // understand at a glance. + let ordered_locations = { + let sort_criterion = |(_, call_data): &(_, &CallData)| { + // Use the first location because that's what the user will see initially + let (lo, hi) = call_data.locations[0].enclosing_item.byte_span; + hi - lo + }; + + let mut locs = call_locations.into_iter().collect::<Vec<_>>(); + 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 suceeds + let write_and_skip_failure = |w: &mut Buffer, it: &mut Peekable<_>| { + while let Some(example) = it.next() { + 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(w, &mut it); + + // Then add the remaining examples in a hidden section. + if it.peek().is_some() { + write!( + w, + "<details class=\"rustdoc-toggle more-examples-toggle\">\ + <summary class=\"hideme\">\ + <span>More examples</span>\ + </summary>\ + <div class=\"more-scraped-examples\">\ + <div class=\"toggle-line\"><div class=\"toggle-line-inner\"></div></div>\ + <div class=\"more-scraped-examples-inner\">" + ); + + // 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(w, &mut it); + } + + // For the remaining examples, generate a <ul> containing links to the source files. + if it.peek().is_some() { + write!(w, r#"<div class="example-links">Additional examples can be found in:<br><ul>"#); + it.for_each(|(_, call_data)| { + write!( + w, + r#"<li><a href="{root}{url}">{name}</a></li>"#, + root = cx.root_path(), + url = call_data.url, + name = call_data.display_name + ); + }); + write!(w, "</ul></div>"); + } + + write!(w, "</div></div></details>"); + } + + write!(w, "</div>"); +} |