diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index 071834c59d65e..89549eae2cb0e 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -32,8 +32,9 @@ use crate::clean::inline; use crate::clean::types::Type::{QPath, ResolvedPath}; use crate::core::DocContext; use crate::doctree; -use crate::html::item_type::ItemType; -use crate::html::render::{cache, ExternalLocation}; +use crate::formats::cache::cache; +use crate::formats::item_type::ItemType; +use crate::html::render::cache::ExternalLocation; use self::FnRetTy::*; use self::ItemEnum::*; @@ -1172,7 +1173,7 @@ impl GetDefId for Type { fn def_id(&self) -> Option { match *self { ResolvedPath { did, .. } => Some(did), - Primitive(p) => crate::html::render::cache().primitive_locations.get(&p).cloned(), + Primitive(p) => cache().primitive_locations.get(&p).cloned(), BorrowedRef { type_: box Generic(..), .. } => { Primitive(PrimitiveType::Reference).def_id() } diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 39e33da44964e..3547b45dfa71f 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -4,6 +4,9 @@ use std::ffi::OsStr; use std::fmt; use std::path::PathBuf; +use rustc_data_structures::fx::{FxHashMap, FxHashSet}; +use rustc_hir::def_id::DefId; +use rustc_middle::middle::privacy::AccessLevels; use rustc_session::config::{self, parse_crate_types_from_list, parse_externs, CrateType}; use rustc_session::config::{ build_codegen_options, build_debugging_options, get_cmd_lint_options, host_triple, @@ -249,6 +252,20 @@ pub struct RenderOptions { pub document_hidden: bool, } +/// Temporary storage for data obtained during `RustdocVisitor::clean()`. +/// Later on moved into `CACHE_KEY`. +#[derive(Default, Clone)] +pub struct RenderInfo { + pub inlined: FxHashSet, + pub external_paths: crate::core::ExternalPaths, + pub exact_paths: FxHashMap>, + pub access_levels: AccessLevels, + pub deref_trait_did: Option, + pub deref_mut_trait_did: Option, + pub owned_box_did: Option, + pub output_format: Option, +} + impl Options { /// Parses the given command-line for options. If an error message or other early-return has /// been printed, returns `Err` with the exit code. diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 263909d5559d1..2c2ebc9291b98 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -32,8 +32,8 @@ use std::rc::Rc; use crate::clean; use crate::clean::{AttributesExt, MAX_DEF_ID}; +use crate::config::RenderInfo; use crate::config::{Options as RustdocOptions, RenderOptions}; -use crate::html::render::RenderInfo; use crate::passes::{self, Condition::*, ConditionalPass}; pub use rustc_session::config::{CodegenOptions, DebuggingOptions, Input, Options}; @@ -44,9 +44,9 @@ pub type ExternalPaths = FxHashMap, clean::TypeKind)>; pub struct DocContext<'tcx> { pub tcx: TyCtxt<'tcx>, pub resolver: Rc>, - /// Later on moved into `html::render::CACHE_KEY` + /// Later on moved into `CACHE_KEY` pub renderinfo: RefCell, - /// Later on moved through `clean::Crate` into `html::render::CACHE_KEY` + /// Later on moved through `clean::Crate` into `CACHE_KEY` pub external_traits: Rc>>, /// Used while populating `external_traits` to ensure we don't process the same trait twice at /// the same time. diff --git a/src/librustdoc/docfs.rs b/src/librustdoc/docfs.rs index 9a11e8fce28b7..4ce6bcbe2749e 100644 --- a/src/librustdoc/docfs.rs +++ b/src/librustdoc/docfs.rs @@ -13,8 +13,7 @@ use std::fs; use std::io; use std::path::Path; use std::string::ToString; -use std::sync::mpsc::{channel, Receiver, Sender}; -use std::sync::Arc; +use std::sync::mpsc::Sender; macro_rules! try_err { ($e:expr, $file:expr) => { @@ -31,47 +30,24 @@ pub trait PathError { S: ToString + Sized; } -pub struct ErrorStorage { - sender: Option>>, - receiver: Receiver>, -} - -impl ErrorStorage { - pub fn new() -> ErrorStorage { - let (sender, receiver) = channel(); - ErrorStorage { sender: Some(sender), receiver } - } - - /// Prints all stored errors. Returns the number of printed errors. - pub fn write_errors(&mut self, diag: &rustc_errors::Handler) -> usize { - let mut printed = 0; - // In order to drop the sender part of the channel. - self.sender = None; - - for msg in self.receiver.iter() { - if let Some(ref error) = msg { - diag.struct_err(&error).emit(); - printed += 1; - } - } - printed - } -} - pub struct DocFS { sync_only: bool, - errors: Arc, + errors: Option>, } impl DocFS { - pub fn new(errors: &Arc) -> DocFS { - DocFS { sync_only: false, errors: Arc::clone(errors) } + pub fn new(errors: Sender) -> DocFS { + DocFS { sync_only: false, errors: Some(errors) } } pub fn set_sync_only(&mut self, sync_only: bool) { self.sync_only = sync_only; } + pub fn close(&mut self) { + self.errors = None; + } + pub fn create_dir_all>(&self, path: P) -> io::Result<()> { // For now, dir creation isn't a huge time consideration, do it // synchronously, which avoids needing ordering between write() actions @@ -88,20 +64,15 @@ impl DocFS { if !self.sync_only && cfg!(windows) { // A possible future enhancement after more detailed profiling would // be to create the file sync so errors are reported eagerly. - let contents = contents.as_ref().to_vec(); let path = path.as_ref().to_path_buf(); - let sender = self.errors.sender.clone().unwrap(); - rayon::spawn(move || match fs::write(&path, &contents) { - Ok(_) => { - sender.send(None).unwrap_or_else(|_| { - panic!("failed to send error on \"{}\"", path.display()) - }); - } - Err(e) => { - sender.send(Some(format!("\"{}\": {}", path.display(), e))).unwrap_or_else( - |_| panic!("failed to send non-error on \"{}\"", path.display()), - ); - } + let contents = contents.as_ref().to_vec(); + let sender = self.errors.clone().expect("can't write after closing"); + rayon::spawn(move || { + fs::write(&path, contents).unwrap_or_else(|e| { + sender + .send(format!("\"{}\": {}", path.display(), e)) + .expect(&format!("failed to send error on \"{}\"", path.display())); + }); }); Ok(()) } else { diff --git a/src/librustdoc/error.rs b/src/librustdoc/error.rs new file mode 100644 index 0000000000000..77063ab4639a1 --- /dev/null +++ b/src/librustdoc/error.rs @@ -0,0 +1,56 @@ +use std::error; +use std::fmt::{self, Formatter}; +use std::path::{Path, PathBuf}; + +use crate::docfs::PathError; + +#[derive(Debug)] +pub struct Error { + pub file: PathBuf, + pub error: String, +} + +impl error::Error for Error {} + +impl std::fmt::Display for Error { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + let file = self.file.display().to_string(); + if file.is_empty() { + write!(f, "{}", self.error) + } else { + write!(f, "\"{}\": {}", self.file.display(), self.error) + } + } +} + +impl PathError for Error { + fn new>(e: S, path: P) -> Error + where + S: ToString + Sized, + { + Error { file: path.as_ref().to_path_buf(), error: e.to_string() } + } +} + +#[macro_export] +macro_rules! try_none { + ($e:expr, $file:expr) => {{ + use std::io; + match $e { + Some(e) => e, + None => { + return Err(Error::new(io::Error::new(io::ErrorKind::Other, "not found"), $file)); + } + } + }}; +} + +#[macro_export] +macro_rules! try_err { + ($e:expr, $file:expr) => {{ + match $e { + Ok(e) => e, + Err(e) => return Err(Error::new(e, $file)), + } + }}; +} diff --git a/src/librustdoc/formats/cache.rs b/src/librustdoc/formats/cache.rs new file mode 100644 index 0000000000000..99b31473f87a3 --- /dev/null +++ b/src/librustdoc/formats/cache.rs @@ -0,0 +1,488 @@ +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::mem; +use std::path::{Path, PathBuf}; +use std::sync::Arc; + +use rustc_data_structures::fx::{FxHashMap, FxHashSet}; +use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX}; +use rustc_middle::middle::privacy::AccessLevels; +use rustc_span::source_map::FileName; + +use crate::clean::{self, GetDefId}; +use crate::config::RenderInfo; +use crate::fold::DocFolder; +use crate::formats::item_type::ItemType; +use crate::formats::Impl; +use crate::html::render::cache::{extern_location, get_index_search_type, ExternalLocation}; +use crate::html::render::IndexItem; +use crate::html::render::{plain_summary_line, shorten}; + +thread_local!(crate static CACHE_KEY: RefCell> = Default::default()); + +/// This cache is used to store information about the `clean::Crate` being +/// rendered in order to provide more useful documentation. This contains +/// information like all implementors of a trait, all traits a type implements, +/// documentation for all known traits, etc. +/// +/// This structure purposefully does not implement `Clone` because it's intended +/// to be a fairly large and expensive structure to clone. Instead this adheres +/// to `Send` so it may be stored in a `Arc` instance and shared among the various +/// rendering threads. +#[derive(Default)] +pub struct Cache { + /// Maps a type ID to all known implementations for that type. This is only + /// recognized for intra-crate `ResolvedPath` types, and is used to print + /// out extra documentation on the page of an enum/struct. + /// + /// The values of the map are a list of implementations and documentation + /// found on that implementation. + pub impls: FxHashMap>, + + /// Maintains a mapping of local crate `DefId`s to the fully qualified name + /// and "short type description" of that node. This is used when generating + /// URLs when a type is being linked to. External paths are not located in + /// this map because the `External` type itself has all the information + /// necessary. + pub paths: FxHashMap, ItemType)>, + + /// Similar to `paths`, but only holds external paths. This is only used for + /// generating explicit hyperlinks to other crates. + pub external_paths: FxHashMap, ItemType)>, + + /// Maps local `DefId`s of exported types to fully qualified paths. + /// Unlike 'paths', this mapping ignores any renames that occur + /// due to 'use' statements. + /// + /// This map is used when writing out the special 'implementors' + /// javascript file. By using the exact path that the type + /// is declared with, we ensure that each path will be identical + /// to the path used if the corresponding type is inlined. By + /// doing this, we can detect duplicate impls on a trait page, and only display + /// the impl for the inlined type. + pub exact_paths: FxHashMap>, + + /// This map contains information about all known traits of this crate. + /// Implementations of a crate should inherit the documentation of the + /// parent trait if no extra documentation is specified, and default methods + /// should show up in documentation about trait implementations. + pub traits: FxHashMap, + + /// When rendering traits, it's often useful to be able to list all + /// implementors of the trait, and this mapping is exactly, that: a mapping + /// of trait ids to the list of known implementors of the trait + pub implementors: FxHashMap>, + + /// Cache of where external crate documentation can be found. + pub extern_locations: FxHashMap, + + /// Cache of where documentation for primitives can be found. + pub primitive_locations: FxHashMap, + + // Note that external items for which `doc(hidden)` applies to are shown as + // non-reachable while local items aren't. This is because we're reusing + // the access levels from the privacy check pass. + pub access_levels: AccessLevels, + + /// The version of the crate being documented, if given from the `--crate-version` flag. + pub crate_version: Option, + + /// Whether to document private items. + /// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions. + pub document_private: bool, + + // Private fields only used when initially crawling a crate to build a cache + stack: Vec, + parent_stack: Vec, + parent_is_trait_impl: bool, + stripped_mod: bool, + masked_crates: FxHashSet, + + pub search_index: Vec, + pub deref_trait_did: Option, + pub deref_mut_trait_did: Option, + pub owned_box_did: Option, + + // In rare case where a structure is defined in one module but implemented + // in another, if the implementing module is parsed before defining module, + // then the fully qualified name of the structure isn't presented in `paths` + // yet when its implementation methods are being indexed. Caches such methods + // and their parent id here and indexes them at the end of crate parsing. + pub orphan_impl_items: Vec<(DefId, clean::Item)>, + + // Similarly to `orphan_impl_items`, sometimes trait impls are picked up + // even though the trait itself is not exported. This can happen if a trait + // was defined in function/expression scope, since the impl will be picked + // up by `collect-trait-impls` but the trait won't be scraped out in the HIR + // crawl. In order to prevent crashes when looking for spotlight traits or + // when gathering trait documentation on a type, hold impls here while + // folding and add them to the cache later on if we find the trait. + orphan_trait_impls: Vec<(DefId, FxHashSet, Impl)>, + + /// Aliases added through `#[doc(alias = "...")]`. Since a few items can have the same alias, + /// we need the alias element to have an array of items. + pub aliases: BTreeMap>, +} + +impl Cache { + pub fn from_krate( + render_info: RenderInfo, + document_private: bool, + extern_html_root_urls: &BTreeMap, + dst: &Path, + mut krate: clean::Crate, + ) -> (clean::Crate, Cache) { + // Crawl the crate to build various caches used for the output + let RenderInfo { + inlined: _, + external_paths, + exact_paths, + access_levels, + deref_trait_did, + deref_mut_trait_did, + owned_box_did, + .. + } = render_info; + + let external_paths = + external_paths.into_iter().map(|(k, (v, t))| (k, (v, ItemType::from(t)))).collect(); + + let mut cache = Cache { + external_paths, + exact_paths, + parent_is_trait_impl: false, + stripped_mod: false, + access_levels, + crate_version: krate.version.take(), + document_private, + traits: krate.external_traits.replace(Default::default()), + deref_trait_did, + deref_mut_trait_did, + owned_box_did, + masked_crates: mem::take(&mut krate.masked_crates), + ..Cache::default() + }; + + // Cache where all our extern crates are located + // FIXME: this part is specific to HTML so it'd be nice to remove it from the common code + for &(n, ref e) in &krate.externs { + let src_root = match e.src { + FileName::Real(ref p) => match p.local_path().parent() { + Some(p) => p.to_path_buf(), + None => PathBuf::new(), + }, + _ => PathBuf::new(), + }; + let extern_url = extern_html_root_urls.get(&e.name).map(|u| &**u); + cache + .extern_locations + .insert(n, (e.name.clone(), src_root, extern_location(e, extern_url, &dst))); + + let did = DefId { krate: n, index: CRATE_DEF_INDEX }; + cache.external_paths.insert(did, (vec![e.name.to_string()], ItemType::Module)); + } + + // Cache where all known primitives have their documentation located. + // + // Favor linking to as local extern as possible, so iterate all crates in + // reverse topological order. + for &(_, ref e) in krate.externs.iter().rev() { + for &(def_id, prim, _) in &e.primitives { + cache.primitive_locations.insert(prim, def_id); + } + } + for &(def_id, prim, _) in &krate.primitives { + cache.primitive_locations.insert(prim, def_id); + } + + cache.stack.push(krate.name.clone()); + krate = cache.fold_crate(krate); + + for (trait_did, dids, impl_) in cache.orphan_trait_impls.drain(..) { + if cache.traits.contains_key(&trait_did) { + for did in dids { + cache.impls.entry(did).or_default().push(impl_.clone()); + } + } + } + + (krate, cache) + } +} + +impl DocFolder for Cache { + fn fold_item(&mut self, item: clean::Item) -> Option { + if item.def_id.is_local() { + debug!("folding {} \"{:?}\", id {:?}", item.type_(), item.name, item.def_id); + } + + // If this is a stripped module, + // we don't want it or its children in the search index. + let orig_stripped_mod = match item.inner { + clean::StrippedItem(box clean::ModuleItem(..)) => { + mem::replace(&mut self.stripped_mod, true) + } + _ => self.stripped_mod, + }; + + // If the impl is from a masked crate or references something from a + // masked crate then remove it completely. + if let clean::ImplItem(ref i) = item.inner { + if self.masked_crates.contains(&item.def_id.krate) + || i.trait_.def_id().map_or(false, |d| self.masked_crates.contains(&d.krate)) + || i.for_.def_id().map_or(false, |d| self.masked_crates.contains(&d.krate)) + { + return None; + } + } + + // Propagate a trait method's documentation to all implementors of the + // trait. + if let clean::TraitItem(ref t) = item.inner { + self.traits.entry(item.def_id).or_insert_with(|| t.clone()); + } + + // Collect all the implementors of traits. + if let clean::ImplItem(ref i) = item.inner { + if let Some(did) = i.trait_.def_id() { + if i.blanket_impl.is_none() { + self.implementors + .entry(did) + .or_default() + .push(Impl { impl_item: item.clone() }); + } + } + } + + // Index this method for searching later on. + if let Some(ref s) = item.name { + let (parent, is_inherent_impl_item) = match item.inner { + clean::StrippedItem(..) => ((None, None), false), + clean::AssocConstItem(..) | clean::TypedefItem(_, true) + if self.parent_is_trait_impl => + { + // skip associated items in trait impls + ((None, None), false) + } + clean::AssocTypeItem(..) + | clean::TyMethodItem(..) + | clean::StructFieldItem(..) + | clean::VariantItem(..) => ( + ( + Some(*self.parent_stack.last().expect("parent_stack is empty")), + Some(&self.stack[..self.stack.len() - 1]), + ), + false, + ), + clean::MethodItem(..) | clean::AssocConstItem(..) => { + if self.parent_stack.is_empty() { + ((None, None), false) + } else { + let last = self.parent_stack.last().expect("parent_stack is empty 2"); + let did = *last; + let path = match self.paths.get(&did) { + // The current stack not necessarily has correlation + // for where the type was defined. On the other + // hand, `paths` always has the right + // information if present. + Some(&( + ref fqp, + ItemType::Trait + | ItemType::Struct + | ItemType::Union + | ItemType::Enum, + )) => Some(&fqp[..fqp.len() - 1]), + Some(..) => Some(&*self.stack), + None => None, + }; + ((Some(*last), path), true) + } + } + _ => ((None, Some(&*self.stack)), false), + }; + + match parent { + (parent, Some(path)) if is_inherent_impl_item || !self.stripped_mod => { + debug_assert!(!item.is_stripped()); + + // A crate has a module at its root, containing all items, + // which should not be indexed. The crate-item itself is + // inserted later on when serializing the search-index. + if item.def_id.index != CRATE_DEF_INDEX { + self.search_index.push(IndexItem { + ty: item.type_(), + name: s.to_string(), + path: path.join("::"), + desc: shorten(plain_summary_line(item.doc_value())), + parent, + parent_idx: None, + search_type: get_index_search_type(&item), + }); + + for alias in item.attrs.get_doc_aliases() { + self.aliases + .entry(alias.to_lowercase()) + .or_insert(Vec::new()) + .push(self.search_index.len() - 1); + } + } + } + (Some(parent), None) if is_inherent_impl_item => { + // We have a parent, but we don't know where they're + // defined yet. Wait for later to index this item. + self.orphan_impl_items.push((parent, item.clone())); + } + _ => {} + } + } + + // Keep track of the fully qualified path for this item. + let pushed = match item.name { + Some(ref n) if !n.is_empty() => { + self.stack.push(n.to_string()); + true + } + _ => false, + }; + + match item.inner { + clean::StructItem(..) + | clean::EnumItem(..) + | clean::TypedefItem(..) + | clean::TraitItem(..) + | clean::FunctionItem(..) + | clean::ModuleItem(..) + | clean::ForeignFunctionItem(..) + | clean::ForeignStaticItem(..) + | clean::ConstantItem(..) + | clean::StaticItem(..) + | clean::UnionItem(..) + | clean::ForeignTypeItem + | clean::MacroItem(..) + | clean::ProcMacroItem(..) + | clean::VariantItem(..) + if !self.stripped_mod => + { + // Re-exported items mean that the same id can show up twice + // in the rustdoc ast that we're looking at. We know, + // however, that a re-exported item doesn't show up in the + // `public_items` map, so we can skip inserting into the + // paths map if there was already an entry present and we're + // not a public item. + if !self.paths.contains_key(&item.def_id) + || self.access_levels.is_public(item.def_id) + { + self.paths.insert(item.def_id, (self.stack.clone(), item.type_())); + } + } + clean::PrimitiveItem(..) => { + self.paths.insert(item.def_id, (self.stack.clone(), item.type_())); + } + + _ => {} + } + + // Maintain the parent stack + let orig_parent_is_trait_impl = self.parent_is_trait_impl; + let parent_pushed = match item.inner { + clean::TraitItem(..) + | clean::EnumItem(..) + | clean::ForeignTypeItem + | clean::StructItem(..) + | clean::UnionItem(..) + | clean::VariantItem(..) => { + self.parent_stack.push(item.def_id); + self.parent_is_trait_impl = false; + true + } + clean::ImplItem(ref i) => { + self.parent_is_trait_impl = i.trait_.is_some(); + match i.for_ { + clean::ResolvedPath { did, .. } => { + self.parent_stack.push(did); + true + } + ref t => { + let prim_did = t + .primitive_type() + .and_then(|t| self.primitive_locations.get(&t).cloned()); + match prim_did { + Some(did) => { + self.parent_stack.push(did); + true + } + None => false, + } + } + } + } + _ => false, + }; + + // Once we've recursively found all the generics, hoard off all the + // implementations elsewhere. + let ret = self.fold_item_recur(item).and_then(|item| { + if let clean::Item { inner: clean::ImplItem(_), .. } = item { + // Figure out the id of this impl. This may map to a + // primitive rather than always to a struct/enum. + // Note: matching twice to restrict the lifetime of the `i` borrow. + let mut dids = FxHashSet::default(); + if let clean::Item { inner: clean::ImplItem(ref i), .. } = item { + match i.for_ { + clean::ResolvedPath { did, .. } + | clean::BorrowedRef { + type_: box clean::ResolvedPath { did, .. }, .. + } => { + dids.insert(did); + } + ref t => { + let did = t + .primitive_type() + .and_then(|t| self.primitive_locations.get(&t).cloned()); + + if let Some(did) = did { + dids.insert(did); + } + } + } + + if let Some(generics) = i.trait_.as_ref().and_then(|t| t.generics()) { + for bound in generics { + if let Some(did) = bound.def_id() { + dids.insert(did); + } + } + } + } else { + unreachable!() + }; + let impl_item = Impl { impl_item: item }; + if impl_item.trait_did().map_or(true, |d| self.traits.contains_key(&d)) { + for did in dids { + self.impls.entry(did).or_insert(vec![]).push(impl_item.clone()); + } + } else { + let trait_did = impl_item.trait_did().expect("no trait did"); + self.orphan_trait_impls.push((trait_did, dids, impl_item)); + } + None + } else { + Some(item) + } + }); + + if pushed { + self.stack.pop().expect("stack already empty"); + } + if parent_pushed { + self.parent_stack.pop().expect("parent stack already empty"); + } + self.stripped_mod = orig_stripped_mod; + self.parent_is_trait_impl = orig_parent_is_trait_impl; + ret + } +} + +crate fn cache() -> Arc { + CACHE_KEY.with(|c| c.borrow().clone()) +} diff --git a/src/librustdoc/html/item_type.rs b/src/librustdoc/formats/item_type.rs similarity index 99% rename from src/librustdoc/html/item_type.rs rename to src/librustdoc/formats/item_type.rs index cc78b4682d231..696bdae94fc88 100644 --- a/src/librustdoc/html/item_type.rs +++ b/src/librustdoc/formats/item_type.rs @@ -13,7 +13,7 @@ use crate::clean; /// The search index uses item types encoded as smaller numbers which equal to /// discriminants. JavaScript then is used to decode them into the original value. /// Consequently, every change to this type should be synchronized to -/// the `itemTypes` mapping table in `static/main.js`. +/// the `itemTypes` mapping table in `html/static/main.js`. /// /// In addition, code in `html::render` uses this enum to generate CSS classes, page prefixes, and /// module headings. If you are adding to this enum and want to ensure that the sidebar also prints diff --git a/src/librustdoc/formats/mod.rs b/src/librustdoc/formats/mod.rs new file mode 100644 index 0000000000000..dcb0184c58cd2 --- /dev/null +++ b/src/librustdoc/formats/mod.rs @@ -0,0 +1,44 @@ +pub mod cache; +pub mod item_type; +pub mod renderer; + +pub use renderer::{run_format, FormatRenderer}; + +use rustc_span::def_id::DefId; + +use crate::clean; +use crate::clean::types::GetDefId; + +/// Specifies whether rendering directly implemented trait items or ones from a certain Deref +/// impl. +pub enum AssocItemRender<'a> { + All, + DerefFor { trait_: &'a clean::Type, type_: &'a clean::Type, deref_mut_: bool }, +} + +/// For different handling of associated items from the Deref target of a type rather than the type +/// itself. +#[derive(Copy, Clone, PartialEq)] +pub enum RenderMode { + Normal, + ForDeref { mut_: bool }, +} + +/// Metadata about implementations for a type or trait. +#[derive(Clone, Debug)] +pub struct Impl { + pub impl_item: clean::Item, +} + +impl Impl { + pub fn inner_impl(&self) -> &clean::Impl { + match self.impl_item.inner { + clean::ImplItem(ref impl_) => impl_, + _ => panic!("non-impl item found in impl"), + } + } + + pub fn trait_did(&self) -> Option { + self.inner_impl().trait_.def_id() + } +} diff --git a/src/librustdoc/formats/renderer.rs b/src/librustdoc/formats/renderer.rs new file mode 100644 index 0000000000000..90ace4d44c47d --- /dev/null +++ b/src/librustdoc/formats/renderer.rs @@ -0,0 +1,106 @@ +use std::sync::Arc; + +use rustc_span::edition::Edition; + +use crate::clean; +use crate::config::{RenderInfo, RenderOptions}; +use crate::error::Error; +use crate::formats::cache::{Cache, CACHE_KEY}; + +/// Allows for different backends to rustdoc to be used with the `run_format()` function. Each +/// backend renderer has hooks for initialization, documenting an item, entering and exiting a +/// module, and cleanup/finalizing output. +pub trait FormatRenderer: Clone { + /// Sets up any state required for the renderer. When this is called the cache has already been + /// populated. + fn init( + krate: clean::Crate, + options: RenderOptions, + render_info: RenderInfo, + edition: Edition, + cache: &mut Cache, + ) -> Result<(Self, clean::Crate), Error>; + + /// Renders a single non-module item. This means no recursive sub-item rendering is required. + fn item(&mut self, item: clean::Item, cache: &Cache) -> Result<(), Error>; + + /// Renders a module (should not handle recursing into children). + fn mod_item_in( + &mut self, + item: &clean::Item, + item_name: &str, + cache: &Cache, + ) -> Result<(), Error>; + + /// Runs after recursively rendering all sub-items of a module. + fn mod_item_out(&mut self, item_name: &str) -> Result<(), Error>; + + /// Post processing hook for cleanup and dumping output to files. + fn after_krate(&mut self, krate: &clean::Crate, cache: &Cache) -> Result<(), Error>; + + /// Called after everything else to write out errors. + fn after_run(&mut self, diag: &rustc_errors::Handler) -> Result<(), Error>; +} + +/// Main method for rendering a crate. +pub fn run_format( + krate: clean::Crate, + options: RenderOptions, + render_info: RenderInfo, + diag: &rustc_errors::Handler, + edition: Edition, +) -> Result<(), Error> { + let (krate, mut cache) = Cache::from_krate( + render_info.clone(), + options.document_private, + &options.extern_html_root_urls, + &options.output, + krate, + ); + + let (mut format_renderer, mut krate) = + T::init(krate, options, render_info, edition, &mut cache)?; + + let cache = Arc::new(cache); + // Freeze the cache now that the index has been built. Put an Arc into TLS for future + // parallelization opportunities + CACHE_KEY.with(|v| *v.borrow_mut() = cache.clone()); + + let mut item = match krate.module.take() { + Some(i) => i, + None => return Ok(()), + }; + + item.name = Some(krate.name.clone()); + + // Render the crate documentation + let mut work = vec![(format_renderer.clone(), item)]; + + while let Some((mut cx, item)) = work.pop() { + if item.is_mod() { + // modules are special because they add a namespace. We also need to + // recurse into the items of the module as well. + let name = item.name.as_ref().unwrap().to_string(); + if name.is_empty() { + panic!("Unexpected module with empty name"); + } + + cx.mod_item_in(&item, &name, &cache)?; + let module = match item.inner { + clean::StrippedItem(box clean::ModuleItem(m)) | clean::ModuleItem(m) => m, + _ => unreachable!(), + }; + for it in module.items { + debug!("Adding {:?} to worklist", it.name); + work.push((cx.clone(), it)); + } + + cx.mod_item_out(&name)?; + } else if item.name.is_some() { + cx.item(item, &cache)?; + } + } + + format_renderer.after_krate(&krate, &cache)?; + format_renderer.after_run(diag) +} diff --git a/src/librustdoc/html/format.rs b/src/librustdoc/html/format.rs index 0d8284029afc7..699f8c36cba6a 100644 --- a/src/librustdoc/html/format.rs +++ b/src/librustdoc/html/format.rs @@ -11,13 +11,15 @@ use std::fmt; use rustc_data_structures::fx::FxHashSet; use rustc_hir as hir; -use rustc_hir::def_id::DefId; +use rustc_span::def_id::DefId; use rustc_target::spec::abi::Abi; use crate::clean::{self, PrimitiveType}; +use crate::formats::cache::cache; +use crate::formats::item_type::ItemType; use crate::html::escape::Escape; -use crate::html::item_type::ItemType; -use crate::html::render::{self, cache, CURRENT_DEPTH}; +use crate::html::render::cache::ExternalLocation; +use crate::html::render::CURRENT_DEPTH; pub trait Print { fn print(self, buffer: &mut Buffer); @@ -493,9 +495,9 @@ pub fn href(did: DefId) -> Option<(String, ItemType, Vec)> { fqp, shortty, match cache.extern_locations[&did.krate] { - (.., render::Remote(ref s)) => s.to_string(), - (.., render::Local) => "../".repeat(depth), - (.., render::Unknown) => return None, + (.., ExternalLocation::Remote(ref s)) => s.to_string(), + (.., ExternalLocation::Local) => "../".repeat(depth), + (.., ExternalLocation::Unknown) => return None, }, ) } @@ -574,12 +576,12 @@ fn primitive_link( } Some(&def_id) => { let loc = match m.extern_locations[&def_id.krate] { - (ref cname, _, render::Remote(ref s)) => Some((cname, s.to_string())), - (ref cname, _, render::Local) => { + (ref cname, _, ExternalLocation::Remote(ref s)) => Some((cname, s.to_string())), + (ref cname, _, ExternalLocation::Local) => { let len = CURRENT_DEPTH.with(|s| s.get()); Some((cname, "../".repeat(len))) } - (.., render::Unknown) => None, + (.., ExternalLocation::Unknown) => None, }; if let Some((cname, root)) = loc { write!( diff --git a/src/librustdoc/html/mod.rs b/src/librustdoc/html/mod.rs new file mode 100644 index 0000000000000..367538d440ea1 --- /dev/null +++ b/src/librustdoc/html/mod.rs @@ -0,0 +1,9 @@ +crate mod escape; +crate mod format; +crate mod highlight; +crate mod layout; +pub mod markdown; +pub mod render; +crate mod sources; +crate mod static_files; +crate mod toc; diff --git a/src/librustdoc/html/render/cache.rs b/src/librustdoc/html/render/cache.rs index 1b5c8a9378e41..378efa1a1bed7 100644 --- a/src/librustdoc/html/render/cache.rs +++ b/src/librustdoc/html/render/cache.rs @@ -1,18 +1,16 @@ -use crate::clean::{self, AttributesExt, GetDefId}; -use crate::fold::DocFolder; -use rustc_data_structures::fx::{FxHashMap, FxHashSet}; -use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX}; -use rustc_middle::middle::privacy::AccessLevels; -use rustc_span::source_map::FileName; -use rustc_span::symbol::sym; use std::collections::BTreeMap; -use std::mem; -use std::path::{Path, PathBuf}; +use std::path::Path; +use rustc_data_structures::fx::FxHashMap; +use rustc_span::symbol::sym; use serde::Serialize; -use super::{plain_summary_line, shorten, Impl, IndexItem, IndexItemFunctionType, ItemType}; -use super::{Generic, RenderInfo, RenderType, TypeWithKind}; +use crate::clean::types::GetDefId; +use crate::clean::{self, AttributesExt}; +use crate::formats::cache::Cache; +use crate::formats::item_type::ItemType; +use crate::html::render::{plain_summary_line, shorten}; +use crate::html::render::{Generic, IndexItem, IndexItemFunctionType, RenderType, TypeWithKind}; /// Indicates where an external crate can be found. pub enum ExternalLocation { @@ -24,483 +22,9 @@ pub enum ExternalLocation { Unknown, } -/// This cache is used to store information about the `clean::Crate` being -/// rendered in order to provide more useful documentation. This contains -/// information like all implementors of a trait, all traits a type implements, -/// documentation for all known traits, etc. -/// -/// This structure purposefully does not implement `Clone` because it's intended -/// to be a fairly large and expensive structure to clone. Instead this adheres -/// to `Send` so it may be stored in a `Arc` instance and shared among the various -/// rendering threads. -#[derive(Default)] -crate struct Cache { - /// Maps a type ID to all known implementations for that type. This is only - /// recognized for intra-crate `ResolvedPath` types, and is used to print - /// out extra documentation on the page of an enum/struct. - /// - /// The values of the map are a list of implementations and documentation - /// found on that implementation. - pub impls: FxHashMap>, - - /// Maintains a mapping of local crate `DefId`s to the fully qualified name - /// and "short type description" of that node. This is used when generating - /// URLs when a type is being linked to. External paths are not located in - /// this map because the `External` type itself has all the information - /// necessary. - pub paths: FxHashMap, ItemType)>, - - /// Similar to `paths`, but only holds external paths. This is only used for - /// generating explicit hyperlinks to other crates. - pub external_paths: FxHashMap, ItemType)>, - - /// Maps local `DefId`s of exported types to fully qualified paths. - /// Unlike 'paths', this mapping ignores any renames that occur - /// due to 'use' statements. - /// - /// This map is used when writing out the special 'implementors' - /// javascript file. By using the exact path that the type - /// is declared with, we ensure that each path will be identical - /// to the path used if the corresponding type is inlined. By - /// doing this, we can detect duplicate impls on a trait page, and only display - /// the impl for the inlined type. - pub exact_paths: FxHashMap>, - - /// This map contains information about all known traits of this crate. - /// Implementations of a crate should inherit the documentation of the - /// parent trait if no extra documentation is specified, and default methods - /// should show up in documentation about trait implementations. - pub traits: FxHashMap, - - /// When rendering traits, it's often useful to be able to list all - /// implementors of the trait, and this mapping is exactly, that: a mapping - /// of trait ids to the list of known implementors of the trait - pub implementors: FxHashMap>, - - /// Cache of where external crate documentation can be found. - pub extern_locations: FxHashMap, - - /// Cache of where documentation for primitives can be found. - pub primitive_locations: FxHashMap, - - // Note that external items for which `doc(hidden)` applies to are shown as - // non-reachable while local items aren't. This is because we're reusing - // the access levels from the privacy check pass. - pub access_levels: AccessLevels, - - /// The version of the crate being documented, if given from the `--crate-version` flag. - pub crate_version: Option, - - /// Whether to document private items. - /// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions. - pub document_private: bool, - - // Private fields only used when initially crawling a crate to build a cache - stack: Vec, - parent_stack: Vec, - parent_is_trait_impl: bool, - search_index: Vec, - stripped_mod: bool, - pub deref_trait_did: Option, - pub deref_mut_trait_did: Option, - pub owned_box_did: Option, - masked_crates: FxHashSet, - - // In rare case where a structure is defined in one module but implemented - // in another, if the implementing module is parsed before defining module, - // then the fully qualified name of the structure isn't presented in `paths` - // yet when its implementation methods are being indexed. Caches such methods - // and their parent id here and indexes them at the end of crate parsing. - orphan_impl_items: Vec<(DefId, clean::Item)>, - - // Similarly to `orphan_impl_items`, sometimes trait impls are picked up - // even though the trait itself is not exported. This can happen if a trait - // was defined in function/expression scope, since the impl will be picked - // up by `collect-trait-impls` but the trait won't be scraped out in the HIR - // crawl. In order to prevent crashes when looking for spotlight traits or - // when gathering trait documentation on a type, hold impls here while - // folding and add them to the cache later on if we find the trait. - orphan_trait_impls: Vec<(DefId, FxHashSet, Impl)>, - - /// Aliases added through `#[doc(alias = "...")]`. Since a few items can have the same alias, - /// we need the alias element to have an array of items. - pub(super) aliases: BTreeMap>, -} - -impl Cache { - pub fn from_krate( - renderinfo: RenderInfo, - document_private: bool, - extern_html_root_urls: &BTreeMap, - dst: &Path, - mut krate: clean::Crate, - ) -> (clean::Crate, String, Cache) { - // Crawl the crate to build various caches used for the output - let RenderInfo { - inlined: _, - external_paths, - exact_paths, - access_levels, - deref_trait_did, - deref_mut_trait_did, - owned_box_did, - .. - } = renderinfo; - - let external_paths = - external_paths.into_iter().map(|(k, (v, t))| (k, (v, ItemType::from(t)))).collect(); - - let mut cache = Cache { - impls: Default::default(), - external_paths, - exact_paths, - paths: Default::default(), - implementors: Default::default(), - stack: Vec::new(), - parent_stack: Vec::new(), - search_index: Vec::new(), - parent_is_trait_impl: false, - extern_locations: Default::default(), - primitive_locations: Default::default(), - stripped_mod: false, - access_levels, - crate_version: krate.version.take(), - document_private, - orphan_impl_items: Vec::new(), - orphan_trait_impls: Vec::new(), - traits: krate.external_traits.replace(Default::default()), - deref_trait_did, - deref_mut_trait_did, - owned_box_did, - masked_crates: mem::take(&mut krate.masked_crates), - aliases: Default::default(), - }; - - // Cache where all our extern crates are located - for &(n, ref e) in &krate.externs { - let src_root = match e.src { - FileName::Real(ref p) => match p.local_path().parent() { - Some(p) => p.to_path_buf(), - None => PathBuf::new(), - }, - _ => PathBuf::new(), - }; - let extern_url = extern_html_root_urls.get(&e.name).map(|u| &**u); - cache - .extern_locations - .insert(n, (e.name.clone(), src_root, extern_location(e, extern_url, &dst))); - - let did = DefId { krate: n, index: CRATE_DEF_INDEX }; - cache.external_paths.insert(did, (vec![e.name.to_string()], ItemType::Module)); - } - - // Cache where all known primitives have their documentation located. - // - // Favor linking to as local extern as possible, so iterate all crates in - // reverse topological order. - for &(_, ref e) in krate.externs.iter().rev() { - for &(def_id, prim, _) in &e.primitives { - cache.primitive_locations.insert(prim, def_id); - } - } - for &(def_id, prim, _) in &krate.primitives { - cache.primitive_locations.insert(prim, def_id); - } - - cache.stack.push(krate.name.clone()); - krate = cache.fold_crate(krate); - - for (trait_did, dids, impl_) in cache.orphan_trait_impls.drain(..) { - if cache.traits.contains_key(&trait_did) { - for did in dids { - cache.impls.entry(did).or_insert(vec![]).push(impl_.clone()); - } - } - } - - // Build our search index - let index = build_index(&krate, &mut cache); - - (krate, index, cache) - } -} - -impl DocFolder for Cache { - fn fold_item(&mut self, item: clean::Item) -> Option { - if item.def_id.is_local() { - debug!("folding {} \"{:?}\", id {:?}", item.type_(), item.name, item.def_id); - } - - // If this is a stripped module, - // we don't want it or its children in the search index. - let orig_stripped_mod = match item.inner { - clean::StrippedItem(box clean::ModuleItem(..)) => { - mem::replace(&mut self.stripped_mod, true) - } - _ => self.stripped_mod, - }; - - // If the impl is from a masked crate or references something from a - // masked crate then remove it completely. - if let clean::ImplItem(ref i) = item.inner { - if self.masked_crates.contains(&item.def_id.krate) - || i.trait_.def_id().map_or(false, |d| self.masked_crates.contains(&d.krate)) - || i.for_.def_id().map_or(false, |d| self.masked_crates.contains(&d.krate)) - { - return None; - } - } - - // Propagate a trait method's documentation to all implementors of the - // trait. - if let clean::TraitItem(ref t) = item.inner { - self.traits.entry(item.def_id).or_insert_with(|| t.clone()); - } - - // Collect all the implementors of traits. - if let clean::ImplItem(ref i) = item.inner { - if let Some(did) = i.trait_.def_id() { - if i.blanket_impl.is_none() { - self.implementors - .entry(did) - .or_default() - .push(Impl { impl_item: item.clone() }); - } - } - } - - // Index this method for searching later on. - if let Some(ref s) = item.name { - let (parent, is_inherent_impl_item) = match item.inner { - clean::StrippedItem(..) => ((None, None), false), - clean::AssocConstItem(..) | clean::TypedefItem(_, true) - if self.parent_is_trait_impl => - { - // skip associated items in trait impls - ((None, None), false) - } - clean::AssocTypeItem(..) - | clean::TyMethodItem(..) - | clean::StructFieldItem(..) - | clean::VariantItem(..) => ( - ( - Some(*self.parent_stack.last().expect("parent_stack is empty")), - Some(&self.stack[..self.stack.len() - 1]), - ), - false, - ), - clean::MethodItem(..) | clean::AssocConstItem(..) => { - if self.parent_stack.is_empty() { - ((None, None), false) - } else { - let last = self.parent_stack.last().expect("parent_stack is empty 2"); - let did = *last; - let path = match self.paths.get(&did) { - // The current stack not necessarily has correlation - // for where the type was defined. On the other - // hand, `paths` always has the right - // information if present. - Some(&( - ref fqp, - ItemType::Trait - | ItemType::Struct - | ItemType::Union - | ItemType::Enum, - )) => Some(&fqp[..fqp.len() - 1]), - Some(..) => Some(&*self.stack), - None => None, - }; - ((Some(*last), path), true) - } - } - _ => ((None, Some(&*self.stack)), false), - }; - - match parent { - (parent, Some(path)) if is_inherent_impl_item || !self.stripped_mod => { - debug_assert!(!item.is_stripped()); - - // A crate has a module at its root, containing all items, - // which should not be indexed. The crate-item itself is - // inserted later on when serializing the search-index. - if item.def_id.index != CRATE_DEF_INDEX { - self.search_index.push(IndexItem { - ty: item.type_(), - name: s.to_string(), - path: path.join("::"), - desc: shorten(plain_summary_line(item.doc_value())), - parent, - parent_idx: None, - search_type: get_index_search_type(&item), - }); - - for alias in item.attrs.get_doc_aliases() { - self.aliases - .entry(alias.to_lowercase()) - .or_insert(Vec::new()) - .push(self.search_index.len() - 1); - } - } - } - (Some(parent), None) if is_inherent_impl_item => { - // We have a parent, but we don't know where they're - // defined yet. Wait for later to index this item. - self.orphan_impl_items.push((parent, item.clone())); - } - _ => {} - } - } - - // Keep track of the fully qualified path for this item. - let pushed = match item.name { - Some(ref n) if !n.is_empty() => { - self.stack.push(n.to_string()); - true - } - _ => false, - }; - - match item.inner { - clean::StructItem(..) - | clean::EnumItem(..) - | clean::TypedefItem(..) - | clean::TraitItem(..) - | clean::FunctionItem(..) - | clean::ModuleItem(..) - | clean::ForeignFunctionItem(..) - | clean::ForeignStaticItem(..) - | clean::ConstantItem(..) - | clean::StaticItem(..) - | clean::UnionItem(..) - | clean::ForeignTypeItem - | clean::MacroItem(..) - | clean::ProcMacroItem(..) - | clean::VariantItem(..) - if !self.stripped_mod => - { - // Re-exported items mean that the same id can show up twice - // in the rustdoc ast that we're looking at. We know, - // however, that a re-exported item doesn't show up in the - // `public_items` map, so we can skip inserting into the - // paths map if there was already an entry present and we're - // not a public item. - if !self.paths.contains_key(&item.def_id) - || self.access_levels.is_public(item.def_id) - { - self.paths.insert(item.def_id, (self.stack.clone(), item.type_())); - } - } - clean::PrimitiveItem(..) => { - self.paths.insert(item.def_id, (self.stack.clone(), item.type_())); - } - - _ => {} - } - - // Maintain the parent stack - let orig_parent_is_trait_impl = self.parent_is_trait_impl; - let parent_pushed = match item.inner { - clean::TraitItem(..) - | clean::EnumItem(..) - | clean::ForeignTypeItem - | clean::StructItem(..) - | clean::UnionItem(..) - | clean::VariantItem(..) => { - self.parent_stack.push(item.def_id); - self.parent_is_trait_impl = false; - true - } - clean::ImplItem(ref i) => { - self.parent_is_trait_impl = i.trait_.is_some(); - match i.for_ { - clean::ResolvedPath { did, .. } => { - self.parent_stack.push(did); - true - } - ref t => { - let prim_did = t - .primitive_type() - .and_then(|t| self.primitive_locations.get(&t).cloned()); - match prim_did { - Some(did) => { - self.parent_stack.push(did); - true - } - None => false, - } - } - } - } - _ => false, - }; - - // Once we've recursively found all the generics, hoard off all the - // implementations elsewhere. - let ret = self.fold_item_recur(item).and_then(|item| { - if let clean::Item { inner: clean::ImplItem(_), .. } = item { - // Figure out the id of this impl. This may map to a - // primitive rather than always to a struct/enum. - // Note: matching twice to restrict the lifetime of the `i` borrow. - let mut dids = FxHashSet::default(); - if let clean::Item { inner: clean::ImplItem(ref i), .. } = item { - match i.for_ { - clean::ResolvedPath { did, .. } - | clean::BorrowedRef { - type_: box clean::ResolvedPath { did, .. }, .. - } => { - dids.insert(did); - } - ref t => { - let did = t - .primitive_type() - .and_then(|t| self.primitive_locations.get(&t).cloned()); - - if let Some(did) = did { - dids.insert(did); - } - } - } - - if let Some(generics) = i.trait_.as_ref().and_then(|t| t.generics()) { - for bound in generics { - if let Some(did) = bound.def_id() { - dids.insert(did); - } - } - } - } else { - unreachable!() - }; - let impl_item = Impl { impl_item: item }; - if impl_item.trait_did().map_or(true, |d| self.traits.contains_key(&d)) { - for did in dids { - self.impls.entry(did).or_insert(vec![]).push(impl_item.clone()); - } - } else { - let trait_did = impl_item.trait_did().expect("no trait did"); - self.orphan_trait_impls.push((trait_did, dids, impl_item)); - } - None - } else { - Some(item) - } - }); - - if pushed { - self.stack.pop().expect("stack already empty"); - } - if parent_pushed { - self.parent_stack.pop().expect("parent stack already empty"); - } - self.stripped_mod = orig_stripped_mod; - self.parent_is_trait_impl = orig_parent_is_trait_impl; - ret - } -} - /// Attempts to find where an external crate is located, given that we're /// rendering in to the specified source destination. -fn extern_location( +pub fn extern_location( e: &clean::ExternalCrate, extern_url: Option<&str>, dst: &Path, @@ -538,7 +62,7 @@ fn extern_location( } /// Builds the search index from the collected metadata -fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String { +pub fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String { let mut defid_to_pathid = FxHashMap::default(); let mut crate_items = Vec::with_capacity(cache.search_index.len()); let mut crate_paths = vec![]; @@ -640,7 +164,7 @@ fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String { ) } -fn get_index_search_type(item: &clean::Item) -> Option { +crate fn get_index_search_type(item: &clean::Item) -> Option { let (all_types, ret_types) = match item.inner { clean::FunctionItem(ref f) => (&f.all_types, &f.ret_types), clean::MethodItem(ref m) => (&m.all_types, &m.ret_types), diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render/mod.rs similarity index 90% rename from src/librustdoc/html/render.rs rename to src/librustdoc/html/render/mod.rs index f7050cf377722..5fb2d9f6f917c 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render/mod.rs @@ -25,14 +25,18 @@ //! These threads are not parallelized (they haven't been a bottleneck yet), and //! both occur before the crate is rendered. +pub mod cache; + +#[cfg(test)] +mod tests; + use std::borrow::Cow; use std::cell::{Cell, RefCell}; use std::cmp::Ordering; use std::collections::{BTreeMap, VecDeque}; use std::default::Default; -use std::error; use std::ffi::OsStr; -use std::fmt::{self, Formatter, Write}; +use std::fmt::{self, Write}; use std::fs::{self, File}; use std::io::prelude::*; use std::io::{self, BufReader}; @@ -40,6 +44,7 @@ use std::path::{Component, Path, PathBuf}; use std::rc::Rc; use std::str; use std::string::ToString; +use std::sync::mpsc::{channel, Receiver}; use std::sync::Arc; use itertools::Itertools; @@ -50,7 +55,6 @@ use rustc_feature::UnstableFeatures; use rustc_hir as hir; use rustc_hir::def_id::{DefId, LOCAL_CRATE}; use rustc_hir::Mutability; -use rustc_middle::middle::privacy::AccessLevels; use rustc_middle::middle::stability; use rustc_span::edition::Edition; use rustc_span::hygiene::MacroKind; @@ -60,26 +64,23 @@ use serde::ser::SerializeSeq; use serde::{Serialize, Serializer}; use crate::clean::{self, AttributesExt, Deprecation, GetDefId, SelfTy, TypeKind}; -use crate::config::{OutputFormat, RenderOptions}; -use crate::docfs::{DocFS, ErrorStorage, PathError}; +use crate::config::RenderInfo; +use crate::config::RenderOptions; +use crate::docfs::{DocFS, PathError}; use crate::doctree; +use crate::error::Error; +use crate::formats::cache::{cache, Cache}; +use crate::formats::item_type::ItemType; +use crate::formats::{AssocItemRender, FormatRenderer, Impl, RenderMode}; use crate::html::escape::Escape; use crate::html::format::fmt_impl_for_trait_page; use crate::html::format::Function; use crate::html::format::{href, print_default_space, print_generic_bounds, WhereClause}; use crate::html::format::{print_abi_with_space, Buffer, PrintWithSpace}; -use crate::html::item_type::ItemType; use crate::html::markdown::{self, ErrorCodes, IdMap, Markdown, MarkdownHtml, MarkdownSummaryLine}; use crate::html::sources; use crate::html::{highlight, layout, static_files}; - -#[cfg(test)] -mod tests; - -mod cache; - -use cache::Cache; -crate use cache::ExternalLocation::{self, *}; +use cache::{build_index, ExternalLocation}; /// A pair of name and its optional document. pub type NameDoc = (String, Option); @@ -90,55 +91,6 @@ crate fn ensure_trailing_slash(v: &str) -> impl fmt::Display + '_ { }) } -#[derive(Debug)] -pub struct Error { - pub file: PathBuf, - pub error: String, -} - -impl error::Error for Error {} - -impl std::fmt::Display for Error { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - let file = self.file.display().to_string(); - if file.is_empty() { - write!(f, "{}", self.error) - } else { - write!(f, "\"{}\": {}", self.file.display(), self.error) - } - } -} - -impl PathError for Error { - fn new>(e: S, path: P) -> Error - where - S: ToString + Sized, - { - Error { file: path.as_ref().to_path_buf(), error: e.to_string() } - } -} - -macro_rules! try_none { - ($e:expr, $file:expr) => {{ - use std::io; - match $e { - Some(e) => e, - None => { - return Err(Error::new(io::Error::new(io::ErrorKind::Other, "not found"), $file)); - } - } - }}; -} - -macro_rules! try_err { - ($e:expr, $file:expr) => {{ - match $e { - Ok(e) => e, - Err(e) => return Err(Error::new(e, $file)), - } - }}; -} - /// Major driving force in all rustdoc rendering. This contains information /// about where in the tree-like hierarchy rendering is occurring and controls /// how the current page is being rendered. @@ -147,7 +99,7 @@ macro_rules! try_err { /// easily cloned because it is cloned per work-job (about once per item in the /// rustdoc tree). #[derive(Clone)] -struct Context { +crate struct Context { /// Current hierarchy of components leading down to what's currently being /// rendered pub current: Vec, @@ -161,7 +113,10 @@ struct Context { /// The map used to ensure all generated 'id=' attributes are unique. id_map: Rc>, pub shared: Arc, - pub cache: Arc, + all: Rc>, + /// Storage for the errors produced while generating documentation so they + /// can be printed together at the end. + pub errors: Rc>, } crate struct SharedContext { @@ -241,53 +196,20 @@ impl SharedContext { } } -/// Metadata about implementations for a type or trait. -#[derive(Clone, Debug)] -pub struct Impl { - pub impl_item: clean::Item, -} - -impl Impl { - fn inner_impl(&self) -> &clean::Impl { - match self.impl_item.inner { - clean::ImplItem(ref impl_) => impl_, - _ => panic!("non-impl item found in impl"), - } - } - - fn trait_did(&self) -> Option { - self.inner_impl().trait_.def_id() - } -} - -/// Temporary storage for data obtained during `RustdocVisitor::clean()`. -/// Later on moved into `CACHE_KEY`. -#[derive(Default)] -pub struct RenderInfo { - pub inlined: FxHashSet, - pub external_paths: crate::core::ExternalPaths, - pub exact_paths: FxHashMap>, - pub access_levels: AccessLevels, - pub deref_trait_did: Option, - pub deref_mut_trait_did: Option, - pub owned_box_did: Option, - pub output_format: Option, -} - // Helper structs for rendering items/sidebars and carrying along contextual // information /// Struct representing one entry in the JS search index. These are all emitted /// by hand to a large JS file at the end of cache-creation. #[derive(Debug)] -struct IndexItem { - ty: ItemType, - name: String, - path: String, - desc: String, - parent: Option, - parent_idx: Option, - search_type: Option, +pub struct IndexItem { + pub ty: ItemType, + pub name: String, + pub path: String, + pub desc: String, + pub parent: Option, + pub parent_idx: Option, + pub search_type: Option, } impl Serialize for IndexItem { @@ -309,7 +231,7 @@ impl Serialize for IndexItem { /// A type used for the search index. #[derive(Debug)] -struct RenderType { +crate struct RenderType { ty: Option, idx: Option, name: Option, @@ -340,7 +262,7 @@ impl Serialize for RenderType { /// A type used for the search index. #[derive(Debug)] -struct Generic { +crate struct Generic { name: String, defid: Option, idx: Option, @@ -361,7 +283,7 @@ impl Serialize for Generic { /// Full type of functions/methods in the search index. #[derive(Debug)] -struct IndexItemFunctionType { +pub struct IndexItemFunctionType { inputs: Vec, output: Option>, } @@ -394,7 +316,7 @@ impl Serialize for IndexItemFunctionType { } #[derive(Debug)] -pub struct TypeWithKind { +crate struct TypeWithKind { ty: RenderType, kind: TypeKind, } @@ -426,7 +348,6 @@ pub struct StylePath { pub disabled: bool, } -thread_local!(static CACHE_KEY: RefCell> = Default::default()); thread_local!(pub static CURRENT_DEPTH: Cell = Cell::new(0)); pub fn initial_ids() -> Vec { @@ -454,147 +375,301 @@ pub fn initial_ids() -> Vec { } /// Generates the documentation for `crate` into the directory `dst` -pub fn run( - mut krate: clean::Crate, - options: RenderOptions, - renderinfo: RenderInfo, - diag: &rustc_errors::Handler, - edition: Edition, -) -> Result<(), Error> { - // need to save a copy of the options for rendering the index page - let md_opts = options.clone(); - let RenderOptions { - output, - external_html, - id_map, - playground_url, - sort_modules_alphabetically, - themes: style_files, - extension_css, - extern_html_root_urls, - resource_suffix, - static_root_path, - generate_search_filter, - document_private, - .. - } = options; - - let src_root = match krate.src { - FileName::Real(ref p) => match p.local_path().parent() { - Some(p) => p.to_path_buf(), - None => PathBuf::new(), - }, - _ => PathBuf::new(), - }; - let mut errors = Arc::new(ErrorStorage::new()); - // If user passed in `--playground-url` arg, we fill in crate name here - let mut playground = None; - if let Some(url) = playground_url { - playground = Some(markdown::Playground { crate_name: Some(krate.name.clone()), url }); - } - let mut layout = layout::Layout { - logo: String::new(), - favicon: String::new(), - external_html, - krate: krate.name.clone(), - css_file_extension: extension_css, - generate_search_filter, - }; - let mut issue_tracker_base_url = None; - let mut include_sources = true; - - // Crawl the crate attributes looking for attributes which control how we're - // going to emit HTML - if let Some(attrs) = krate.module.as_ref().map(|m| &m.attrs) { - for attr in attrs.lists(sym::doc) { - match (attr.name_or_empty(), attr.value_str()) { - (sym::html_favicon_url, Some(s)) => { - layout.favicon = s.to_string(); - } - (sym::html_logo_url, Some(s)) => { - layout.logo = s.to_string(); - } - (sym::html_playground_url, Some(s)) => { - playground = Some(markdown::Playground { - crate_name: Some(krate.name.clone()), - url: s.to_string(), - }); - } - (sym::issue_tracker_base_url, Some(s)) => { - issue_tracker_base_url = Some(s.to_string()); - } - (sym::html_no_source, None) if attr.is_word() => { - include_sources = false; +impl FormatRenderer for Context { + fn init( + mut krate: clean::Crate, + options: RenderOptions, + _render_info: RenderInfo, + edition: Edition, + cache: &mut Cache, + ) -> Result<(Context, clean::Crate), Error> { + // need to save a copy of the options for rendering the index page + let md_opts = options.clone(); + let RenderOptions { + output, + external_html, + id_map, + playground_url, + sort_modules_alphabetically, + themes: style_files, + extension_css, + resource_suffix, + static_root_path, + generate_search_filter, + .. + } = options; + + let src_root = match krate.src { + FileName::Real(ref p) => match p.local_path().parent() { + Some(p) => p.to_path_buf(), + None => PathBuf::new(), + }, + _ => PathBuf::new(), + }; + // If user passed in `--playground-url` arg, we fill in crate name here + let mut playground = None; + if let Some(url) = playground_url { + playground = Some(markdown::Playground { crate_name: Some(krate.name.clone()), url }); + } + let mut layout = layout::Layout { + logo: String::new(), + favicon: String::new(), + external_html, + krate: krate.name.clone(), + css_file_extension: extension_css, + generate_search_filter, + }; + let mut issue_tracker_base_url = None; + let mut include_sources = true; + + // Crawl the crate attributes looking for attributes which control how we're + // going to emit HTML + if let Some(attrs) = krate.module.as_ref().map(|m| &m.attrs) { + for attr in attrs.lists(sym::doc) { + match (attr.name_or_empty(), attr.value_str()) { + (sym::html_favicon_url, Some(s)) => { + layout.favicon = s.to_string(); + } + (sym::html_logo_url, Some(s)) => { + layout.logo = s.to_string(); + } + (sym::html_playground_url, Some(s)) => { + playground = Some(markdown::Playground { + crate_name: Some(krate.name.clone()), + url: s.to_string(), + }); + } + (sym::issue_tracker_base_url, Some(s)) => { + issue_tracker_base_url = Some(s.to_string()); + } + (sym::html_no_source, None) if attr.is_word() => { + include_sources = false; + } + _ => {} } - _ => {} } } + let (sender, receiver) = channel(); + let mut scx = SharedContext { + collapsed: krate.collapsed, + src_root, + include_sources, + local_sources: Default::default(), + issue_tracker_base_url, + layout, + created_dirs: Default::default(), + sort_modules_alphabetically, + style_files, + resource_suffix, + static_root_path, + fs: DocFS::new(sender), + edition, + codes: ErrorCodes::from(UnstableFeatures::from_environment().is_nightly_build()), + playground, + }; + + // Add the default themes to the `Vec` of stylepaths + // + // Note that these must be added before `sources::render` is called + // so that the resulting source pages are styled + // + // `light.css` is not disabled because it is the stylesheet that stays loaded + // by the browser as the theme stylesheet. The theme system (hackily) works by + // changing the href to this stylesheet. All other themes are disabled to + // prevent rule conflicts + scx.style_files.push(StylePath { path: PathBuf::from("light.css"), disabled: false }); + scx.style_files.push(StylePath { path: PathBuf::from("dark.css"), disabled: true }); + scx.style_files.push(StylePath { path: PathBuf::from("ayu.css"), disabled: true }); + + let dst = output; + scx.ensure_dir(&dst)?; + krate = sources::render(&dst, &mut scx, krate)?; + + // Build our search index + let index = build_index(&krate, cache); + + let cache = Arc::new(cache); + let mut cx = Context { + current: Vec::new(), + dst, + render_redirect_pages: false, + id_map: Rc::new(RefCell::new(id_map)), + shared: Arc::new(scx), + all: Rc::new(RefCell::new(AllTypes::new())), + errors: Rc::new(receiver), + }; + + CURRENT_DEPTH.with(|s| s.set(0)); + + // Write shared runs within a flock; disable thread dispatching of IO temporarily. + Arc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(true); + write_shared(&cx, &krate, index, &md_opts, &cache)?; + Arc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(false); + Ok((cx, krate)) } - let mut scx = SharedContext { - collapsed: krate.collapsed, - src_root, - include_sources, - local_sources: Default::default(), - issue_tracker_base_url, - layout, - created_dirs: Default::default(), - sort_modules_alphabetically, - style_files, - resource_suffix, - static_root_path, - fs: DocFS::new(&errors), - edition, - codes: ErrorCodes::from(UnstableFeatures::from_environment().is_nightly_build()), - playground, - }; - // Add the default themes to the `Vec` of stylepaths - // - // Note that these must be added before `sources::render` is called - // so that the resulting source pages are styled - // - // `light.css` is not disabled because it is the stylesheet that stays loaded - // by the browser as the theme stylesheet. The theme system (hackily) works by - // changing the href to this stylesheet. All other themes are disabled to - // prevent rule conflicts - scx.style_files.push(StylePath { path: PathBuf::from("light.css"), disabled: false }); - scx.style_files.push(StylePath { path: PathBuf::from("dark.css"), disabled: true }); - scx.style_files.push(StylePath { path: PathBuf::from("ayu.css"), disabled: true }); - - let dst = output; - scx.ensure_dir(&dst)?; - krate = sources::render(&dst, &mut scx, krate)?; - let (new_crate, index, cache) = - Cache::from_krate(renderinfo, document_private, &extern_html_root_urls, &dst, krate); - krate = new_crate; - let cache = Arc::new(cache); - let mut cx = Context { - current: Vec::new(), - dst, - render_redirect_pages: false, - id_map: Rc::new(RefCell::new(id_map)), - shared: Arc::new(scx), - cache: cache.clone(), - }; + fn after_run(&mut self, diag: &rustc_errors::Handler) -> Result<(), Error> { + Arc::get_mut(&mut self.shared).unwrap().fs.close(); + let nb_errors = self.errors.iter().map(|err| diag.struct_err(&err).emit()).count(); + if nb_errors > 0 { + Err(Error::new(io::Error::new(io::ErrorKind::Other, "I/O error"), "")) + } else { + Ok(()) + } + } + + fn after_krate(&mut self, krate: &clean::Crate, cache: &Cache) -> Result<(), Error> { + let final_file = self.dst.join(&krate.name).join("all.html"); + let settings_file = self.dst.join("settings.html"); + let crate_name = krate.name.clone(); - // Freeze the cache now that the index has been built. Put an Arc into TLS - // for future parallelization opportunities - CACHE_KEY.with(|v| *v.borrow_mut() = cache.clone()); - CURRENT_DEPTH.with(|s| s.set(0)); + let mut root_path = self.dst.to_str().expect("invalid path").to_owned(); + if !root_path.ends_with('/') { + root_path.push('/'); + } + let mut page = layout::Page { + title: "List of all items in this crate", + css_class: "mod", + root_path: "../", + static_root_path: self.shared.static_root_path.as_deref(), + description: "List of all items in this crate", + keywords: BASIC_KEYWORDS, + resource_suffix: &self.shared.resource_suffix, + extra_scripts: &[], + static_extra_scripts: &[], + }; + let sidebar = if let Some(ref version) = cache.crate_version { + format!( + "

Crate {}

\ +
\ +

Version {}

\ +
\ +

Back to index

", + crate_name, + Escape(version), + ) + } else { + String::new() + }; + let all = self.all.replace(AllTypes::new()); + let v = layout::render( + &self.shared.layout, + &page, + sidebar, + |buf: &mut Buffer| all.print(buf), + &self.shared.style_files, + ); + self.shared.fs.write(&final_file, v.as_bytes())?; - // Write shared runs within a flock; disable thread dispatching of IO temporarily. - Arc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(true); - write_shared(&cx, &krate, index, &md_opts)?; - Arc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(false); + // Generating settings page. + page.title = "Rustdoc settings"; + page.description = "Settings of Rustdoc"; + page.root_path = "./"; - // And finally render the whole crate's documentation - let ret = cx.krate(krate); - let nb_errors = Arc::get_mut(&mut errors).map_or_else(|| 0, |errors| errors.write_errors(diag)); - if ret.is_err() { - ret - } else if nb_errors > 0 { - Err(Error::new(io::Error::new(io::ErrorKind::Other, "I/O error"), "")) - } else { + let mut style_files = self.shared.style_files.clone(); + let sidebar = "

Settings

"; + style_files.push(StylePath { path: PathBuf::from("settings.css"), disabled: false }); + let v = layout::render( + &self.shared.layout, + &page, + sidebar, + settings( + self.shared.static_root_path.as_deref().unwrap_or("./"), + &self.shared.resource_suffix, + ), + &style_files, + ); + self.shared.fs.write(&settings_file, v.as_bytes())?; + Ok(()) + } + + fn mod_item_in( + &mut self, + item: &clean::Item, + item_name: &str, + cache: &Cache, + ) -> Result<(), Error> { + // Stripped modules survive the rustdoc passes (i.e., `strip-private`) + // if they contain impls for public types. These modules can also + // contain items such as publicly re-exported structures. + // + // External crates will provide links to these structures, so + // these modules are recursed into, but not rendered normally + // (a flag on the context). + if !self.render_redirect_pages { + self.render_redirect_pages = item.is_stripped(); + } + let scx = &self.shared; + self.dst.push(item_name); + self.current.push(item_name.to_owned()); + + info!("Recursing into {}", self.dst.display()); + + let buf = self.render_item(item, false, cache); + // buf will be empty if the module is stripped and there is no redirect for it + if !buf.is_empty() { + self.shared.ensure_dir(&self.dst)?; + let joint_dst = self.dst.join("index.html"); + scx.fs.write(&joint_dst, buf.as_bytes())?; + } + + // Render sidebar-items.js used throughout this module. + if !self.render_redirect_pages { + let module = match item.inner { + clean::StrippedItem(box clean::ModuleItem(ref m)) | clean::ModuleItem(ref m) => m, + _ => unreachable!(), + }; + let items = self.build_sidebar_items(module); + let js_dst = self.dst.join("sidebar-items.js"); + let v = format!("initSidebarItems({});", serde_json::to_string(&items).unwrap()); + scx.fs.write(&js_dst, &v)?; + } + Ok(()) + } + + fn mod_item_out(&mut self, _item_name: &str) -> Result<(), Error> { + info!("Recursed; leaving {}", self.dst.display()); + + // Go back to where we were at + self.dst.pop(); + self.current.pop(); + Ok(()) + } + + fn item(&mut self, item: clean::Item, cache: &Cache) -> Result<(), Error> { + // Stripped modules survive the rustdoc passes (i.e., `strip-private`) + // if they contain impls for public types. These modules can also + // contain items such as publicly re-exported structures. + // + // External crates will provide links to these structures, so + // these modules are recursed into, but not rendered normally + // (a flag on the context). + if !self.render_redirect_pages { + self.render_redirect_pages = item.is_stripped(); + } + + let buf = self.render_item(&item, true, cache); + // buf will be empty if the item is stripped and there is no redirect for it + if !buf.is_empty() { + let name = item.name.as_ref().unwrap(); + let item_type = item.type_(); + let file_name = &item_path(item_type, name); + self.shared.ensure_dir(&self.dst)?; + let joint_dst = self.dst.join(file_name); + self.shared.fs.write(&joint_dst, buf.as_bytes())?; + + if !self.render_redirect_pages { + self.all.borrow_mut().append(full_path(self, &item), &item_type); + } + // If the item is a macro, redirect from the old macro URL (with !) + // to the new one (without). + if item_type == ItemType::Macro { + let redir_name = format!("{}.{}!.html", item_type, name); + let redir_dst = self.dst.join(redir_name); + let v = layout::redirect(file_name); + self.shared.fs.write(&redir_dst, v.as_bytes())?; + } + } Ok(()) } } @@ -604,6 +679,7 @@ fn write_shared( krate: &clean::Crate, search_index: String, options: &RenderOptions, + cache: &Cache, ) -> Result<(), Error> { // Write out the shared files. Note that these are shared among all rustdoc // docs placed in the output directory, so this needs to be a synchronized @@ -1001,7 +1077,7 @@ themePicker.onblur = handleThemeButtonsBlur; // Update the list of all implementors for traits let dst = cx.dst.join("implementors"); - for (&did, imps) in &cx.cache.implementors { + for (&did, imps) in &cache.implementors { // Private modules can leak through to this phase of rustdoc, which // could contain implementations for otherwise private types. In some // rare cases we could find an implementation for an item which wasn't @@ -1009,9 +1085,9 @@ themePicker.onblur = handleThemeButtonsBlur; // // FIXME: this is a vague explanation for why this can't be a `get`, in // theory it should be... - let &(ref remote_path, remote_item_type) = match cx.cache.paths.get(&did) { + let &(ref remote_path, remote_item_type) = match cache.paths.get(&did) { Some(p) => p, - None => match cx.cache.external_paths.get(&did) { + None => match cache.external_paths.get(&did) { Some(p) => p, None => continue, }, @@ -1049,7 +1125,7 @@ themePicker.onblur = handleThemeButtonsBlur; // Only create a js file if we have impls to add to it. If the trait is // documented locally though we always create the file to avoid dead // links. - if implementors.is_empty() && !cx.cache.paths.contains_key(&did) { + if implementors.is_empty() && !cache.paths.contains_key(&did) { continue; } @@ -1354,93 +1430,7 @@ impl Context { "../".repeat(self.current.len()) } - /// Main method for rendering a crate. - /// - /// This currently isn't parallelized, but it'd be pretty easy to add - /// parallelization to this function. - fn krate(self, mut krate: clean::Crate) -> Result<(), Error> { - let mut item = match krate.module.take() { - Some(i) => i, - None => return Ok(()), - }; - let final_file = self.dst.join(&krate.name).join("all.html"); - let settings_file = self.dst.join("settings.html"); - - let crate_name = krate.name.clone(); - item.name = Some(krate.name); - - let mut all = AllTypes::new(); - - { - // Render the crate documentation - let mut work = vec![(self.clone(), item)]; - - while let Some((mut cx, item)) = work.pop() { - cx.item(item, &mut all, |cx, item| work.push((cx.clone(), item)))? - } - } - - let mut root_path = self.dst.to_str().expect("invalid path").to_owned(); - if !root_path.ends_with('/') { - root_path.push('/'); - } - let mut page = layout::Page { - title: "List of all items in this crate", - css_class: "mod", - root_path: "../", - static_root_path: self.shared.static_root_path.as_deref(), - description: "List of all items in this crate", - keywords: BASIC_KEYWORDS, - resource_suffix: &self.shared.resource_suffix, - extra_scripts: &[], - static_extra_scripts: &[], - }; - let sidebar = if let Some(ref version) = self.cache.crate_version { - format!( - "

Crate {}

\ -
\ -

Version {}

\ -
\ -

Back to index

", - crate_name, - Escape(version), - ) - } else { - String::new() - }; - let v = layout::render( - &self.shared.layout, - &page, - sidebar, - |buf: &mut Buffer| all.print(buf), - &self.shared.style_files, - ); - self.shared.fs.write(&final_file, v.as_bytes())?; - - // Generating settings page. - page.title = "Rustdoc settings"; - page.description = "Settings of Rustdoc"; - page.root_path = "./"; - - let mut style_files = self.shared.style_files.clone(); - let sidebar = "

Settings

"; - style_files.push(StylePath { path: PathBuf::from("settings.css"), disabled: false }); - let v = layout::render( - &self.shared.layout, - &page, - sidebar, - settings( - self.shared.static_root_path.as_deref().unwrap_or("./"), - &self.shared.resource_suffix, - ), - &style_files, - ); - self.shared.fs.write(&settings_file, v.as_bytes())?; - - Ok(()) - } - - fn render_item(&self, it: &clean::Item, pushname: bool) -> String { + fn render_item(&self, it: &clean::Item, pushname: bool, cache: &Cache) -> String { // A little unfortunate that this is done like this, but it sure // does make formatting *a lot* nicer. CURRENT_DEPTH.with(|slot| { @@ -1493,13 +1483,13 @@ impl Context { layout::render( &self.shared.layout, &page, - |buf: &mut _| print_sidebar(self, it, buf), - |buf: &mut _| print_item(self, it, buf), + |buf: &mut _| print_sidebar(self, it, buf, cache), + |buf: &mut _| print_item(self, it, buf, cache), &self.shared.style_files, ) } else { let mut url = self.root_path(); - if let Some(&(ref names, ty)) = self.cache.paths.get(&it.def_id) { + if let Some(&(ref names, ty)) = cache.paths.get(&it.def_id) { for name in &names[..names.len() - 1] { url.push_str(name); url.push_str("/"); @@ -1512,97 +1502,6 @@ impl Context { } } - /// Non-parallelized version of rendering an item. This will take the input - /// item, render its contents, and then invoke the specified closure with - /// all sub-items which need to be rendered. - /// - /// The rendering driver uses this closure to queue up more work. - fn item(&mut self, item: clean::Item, all: &mut AllTypes, mut f: F) -> Result<(), Error> - where - F: FnMut(&mut Context, clean::Item), - { - // Stripped modules survive the rustdoc passes (i.e., `strip-private`) - // if they contain impls for public types. These modules can also - // contain items such as publicly re-exported structures. - // - // External crates will provide links to these structures, so - // these modules are recursed into, but not rendered normally - // (a flag on the context). - if !self.render_redirect_pages { - self.render_redirect_pages = item.is_stripped(); - } - - if item.is_mod() { - // modules are special because they add a namespace. We also need to - // recurse into the items of the module as well. - let name = item.name.as_ref().unwrap().to_string(); - let scx = &self.shared; - if name.is_empty() { - panic!("Unexpected empty destination: {:?}", self.current); - } - let prev = self.dst.clone(); - self.dst.push(&name); - self.current.push(name); - - info!("Recursing into {}", self.dst.display()); - - let buf = self.render_item(&item, false); - // buf will be empty if the module is stripped and there is no redirect for it - if !buf.is_empty() { - self.shared.ensure_dir(&self.dst)?; - let joint_dst = self.dst.join("index.html"); - scx.fs.write(&joint_dst, buf.as_bytes())?; - } - - let m = match item.inner { - clean::StrippedItem(box clean::ModuleItem(m)) | clean::ModuleItem(m) => m, - _ => unreachable!(), - }; - - // Render sidebar-items.js used throughout this module. - if !self.render_redirect_pages { - let items = self.build_sidebar_items(&m); - let js_dst = self.dst.join("sidebar-items.js"); - let v = format!("initSidebarItems({});", serde_json::to_string(&items).unwrap()); - scx.fs.write(&js_dst, &v)?; - } - - for item in m.items { - f(self, item); - } - - info!("Recursed; leaving {}", self.dst.display()); - - // Go back to where we were at - self.dst = prev; - self.current.pop().unwrap(); - } else if item.name.is_some() { - let buf = self.render_item(&item, true); - // buf will be empty if the item is stripped and there is no redirect for it - if !buf.is_empty() { - let name = item.name.as_ref().unwrap(); - let item_type = item.type_(); - let file_name = &item_path(item_type, name); - self.shared.ensure_dir(&self.dst)?; - let joint_dst = self.dst.join(file_name); - self.shared.fs.write(&joint_dst, buf.as_bytes())?; - - if !self.render_redirect_pages { - all.append(full_path(self, &item), &item_type); - } - // If the item is a macro, redirect from the old macro URL (with !) - // to the new one (without). - if item_type == ItemType::Macro { - let redir_name = format!("{}.{}!.html", item_type, name); - let redir_dst = self.dst.join(redir_name); - let v = layout::redirect(file_name); - self.shared.fs.write(&redir_dst, v.as_bytes())?; - } - } - } - Ok(()) - } - fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap> { // BTreeMap instead of HashMap to get a sorted output let mut map: BTreeMap<_, Vec<_>> = BTreeMap::new(); @@ -1629,9 +1528,7 @@ impl Context { } map } -} -impl Context { /// Generates a url appropriate for an `href` attribute back to the source of /// this item. /// @@ -1641,7 +1538,7 @@ impl Context { /// If `None` is returned, then a source link couldn't be generated. This /// may happen, for example, with externally inlined items where the source /// of their crate documentation isn't known. - fn src_href(&self, item: &clean::Item) -> Option { + fn src_href(&self, item: &clean::Item, cache: &Cache) -> Option { let mut root = self.root_path(); let mut path = String::new(); @@ -1660,13 +1557,13 @@ impl Context { return None; } } else { - let (krate, src_root) = match *self.cache.extern_locations.get(&item.source.cnum)? { - (ref name, ref src, Local) => (name, src), - (ref name, ref src, Remote(ref s)) => { + let (krate, src_root) = match *cache.extern_locations.get(&item.source.cnum)? { + (ref name, ref src, ExternalLocation::Local) => (name, src), + (ref name, ref src, ExternalLocation::Remote(ref s)) => { root = s.to_string(); (name, src) } - (_, _, Unknown) => return None, + (_, _, ExternalLocation::Unknown) => return None, }; sources::clean_path(&src_root, file, false, |component| { @@ -1703,7 +1600,7 @@ where write!(w, "") } -fn print_item(cx: &Context, item: &clean::Item, buf: &mut Buffer) { +fn print_item(cx: &Context, item: &clean::Item, buf: &mut Buffer, cache: &Cache) { debug_assert!(!item.is_stripped()); // Write the breadcrumb trail header for the top write!(buf, "

"); @@ -1731,7 +1628,7 @@ fn print_item(cx: &Context, item: &clean::Item, buf: &mut Buffer) { // this page, and this link will be auto-clicked. The `id` attribute is // used to find the link to auto-click. if cx.shared.include_sources && !item.is_primitive() { - if let Some(l) = cx.src_href(item) { + if let Some(l) = cx.src_href(item, cache) { write!(buf, "[src]", l, "goto source code"); } } @@ -1792,20 +1689,20 @@ fn print_item(cx: &Context, item: &clean::Item, buf: &mut Buffer) { clean::FunctionItem(ref f) | clean::ForeignFunctionItem(ref f) => { item_function(buf, cx, item, f) } - clean::TraitItem(ref t) => item_trait(buf, cx, item, t), - clean::StructItem(ref s) => item_struct(buf, cx, item, s), - clean::UnionItem(ref s) => item_union(buf, cx, item, s), - clean::EnumItem(ref e) => item_enum(buf, cx, item, e), - clean::TypedefItem(ref t, _) => item_typedef(buf, cx, item, t), + clean::TraitItem(ref t) => item_trait(buf, cx, item, t, cache), + clean::StructItem(ref s) => item_struct(buf, cx, item, s, cache), + clean::UnionItem(ref s) => item_union(buf, cx, item, s, cache), + clean::EnumItem(ref e) => item_enum(buf, cx, item, e, cache), + clean::TypedefItem(ref t, _) => item_typedef(buf, cx, item, t, cache), clean::MacroItem(ref m) => item_macro(buf, cx, item, m), clean::ProcMacroItem(ref m) => item_proc_macro(buf, cx, item, m), - clean::PrimitiveItem(_) => item_primitive(buf, cx, item), + clean::PrimitiveItem(_) => item_primitive(buf, cx, item, cache), clean::StaticItem(ref i) | clean::ForeignStaticItem(ref i) => item_static(buf, cx, item, i), clean::ConstantItem(ref c) => item_constant(buf, cx, item, c), - clean::ForeignTypeItem => item_foreign_type(buf, cx, item), + clean::ForeignTypeItem => item_foreign_type(buf, cx, item, cache), clean::KeywordItem(_) => item_keyword(buf, cx, item), - clean::OpaqueTyItem(ref e, _) => item_opaque_ty(buf, cx, item, e), - clean::TraitAliasItem(ref ta) => item_trait_alias(buf, cx, item, ta), + clean::OpaqueTyItem(ref e, _) => item_opaque_ty(buf, cx, item, e, cache), + clean::TraitAliasItem(ref ta) => item_trait_alias(buf, cx, item, ta, cache), _ => { // We don't generate pages for any other type. unreachable!(); @@ -1828,7 +1725,7 @@ fn full_path(cx: &Context, item: &clean::Item) -> String { } #[inline] -fn plain_summary_line(s: Option<&str>) -> String { +crate fn plain_summary_line(s: Option<&str>) -> String { let s = s.unwrap_or(""); // This essentially gets the first paragraph of text in one line. let mut line = s @@ -1845,7 +1742,7 @@ fn plain_summary_line(s: Option<&str>) -> String { markdown::plain_summary_line(&line[..]) } -fn shorten(s: String) -> String { +crate fn shorten(s: String) -> String { if s.chars().count() > 60 { let mut len = 0; let mut ret = s @@ -2415,6 +2312,7 @@ fn render_implementor( w: &mut Buffer, implementor_dups: &FxHashMap<&str, (DefId, bool)>, aliases: &[String], + cache: &Cache, ) { // If there's already another implementor that has the same abbridged name, use the // full path, for example in `std::iter::ExactSizeIterator` @@ -2438,10 +2336,17 @@ fn render_implementor( false, false, aliases, + cache, ); } -fn render_impls(cx: &Context, w: &mut Buffer, traits: &[&&Impl], containing_item: &clean::Item) { +fn render_impls( + cx: &Context, + w: &mut Buffer, + traits: &[&&Impl], + containing_item: &clean::Item, + cache: &Cache, +) { let mut impls = traits .iter() .map(|i| { @@ -2460,6 +2365,7 @@ fn render_impls(cx: &Context, w: &mut Buffer, traits: &[&&Impl], containing_item false, true, &[], + cache, ); buffer.into_inner() }) @@ -2492,7 +2398,7 @@ fn compare_impl<'a, 'b>(lhs: &'a &&Impl, rhs: &'b &&Impl) -> Ordering { name_key(&lhs).cmp(&name_key(&rhs)) } -fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) { +fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait, cache: &Cache) { let bounds = bounds(&t.bounds, false); let types = t.items.iter().filter(|m| m.is_associated_type()).collect::>(); let consts = t.items.iter().filter(|m| m.is_associated_const()).collect::>(); @@ -2652,9 +2558,9 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) } // If there are methods directly on this trait object, render them here. - render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All); + render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache); - if let Some(implementors) = cx.cache.implementors.get(&it.def_id) { + if let Some(implementors) = cache.implementors.get(&it.def_id) { // The DefId is for the first Type found with that name. The bool is // if any Types with the same name but different DefId have been found. let mut implementor_dups: FxHashMap<&str, (DefId, bool)> = FxHashMap::default(); @@ -2676,7 +2582,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) } let (local, foreign) = implementors.iter().partition::, _>(|i| { - i.inner_impl().for_.def_id().map_or(true, |d| cx.cache.paths.contains_key(&d)) + i.inner_impl().for_.def_id().map_or(true, |d| cache.paths.contains_key(&d)) }); let (mut synthetic, mut concrete): (Vec<&&Impl>, Vec<&&Impl>) = @@ -2705,6 +2611,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) true, false, &[], + cache, ); } write_loading_content(w, ""); @@ -2717,7 +2624,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) "
", ); for implementor in concrete { - render_implementor(cx, implementor, w, &implementor_dups, &[]); + render_implementor(cx, implementor, w, &implementor_dups, &[], cache); } write_loading_content(w, "
"); @@ -2735,6 +2642,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) w, &implementor_dups, &collect_paths_for_type(implementor.inner_impl().for_.clone()), + cache, ); } write_loading_content(w, ""); @@ -2770,7 +2678,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) path = if it.def_id.is_local() { cx.current.join("/") } else { - let (ref path, _) = cx.cache.external_paths[&it.def_id]; + let (ref path, _) = cache.external_paths[&it.def_id]; path[..path.len() - 1].join("/") }, ty = it.type_(), @@ -2779,7 +2687,7 @@ fn item_trait(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Trait) } fn naive_assoc_href(it: &clean::Item, link: AssocItemLink<'_>) -> String { - use crate::html::item_type::ItemType::*; + use crate::formats::item_type::ItemType::*; let name = it.name.as_ref().unwrap(); let ty = match it.type_() { @@ -2945,7 +2853,7 @@ fn render_assoc_item( } } -fn item_struct(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Struct) { +fn item_struct(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Struct, cache: &Cache) { wrap_into_docblock(w, |w| { write!(w, "
");
         render_attributes(w, it, true);
@@ -2992,10 +2900,10 @@ fn item_struct(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Struct
             }
         }
     }
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn item_union(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Union) {
+fn item_union(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Union, cache: &Cache) {
     wrap_into_docblock(w, |w| {
         write!(w, "
");
         render_attributes(w, it, true);
@@ -3038,10 +2946,10 @@ fn item_union(w: &mut Buffer, cx: &Context, it: &clean::Item, s: &clean::Union)
             document(w, cx, field);
         }
     }
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn item_enum(w: &mut Buffer, cx: &Context, it: &clean::Item, e: &clean::Enum) {
+fn item_enum(w: &mut Buffer, cx: &Context, it: &clean::Item, e: &clean::Enum, cache: &Cache) {
     wrap_into_docblock(w, |w| {
         write!(w, "
");
         render_attributes(w, it, true);
@@ -3166,7 +3074,7 @@ fn item_enum(w: &mut Buffer, cx: &Context, it: &clean::Item, e: &clean::Enum) {
             render_stability_since(w, variant, it);
         }
     }
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
 const ALLOWED_ATTRIBUTES: &[Symbol] = &[
@@ -3348,26 +3256,15 @@ impl<'a> AssocItemLink<'a> {
     }
 }
 
-enum AssocItemRender<'a> {
-    All,
-    DerefFor { trait_: &'a clean::Type, type_: &'a clean::Type, deref_mut_: bool },
-}
-
-#[derive(Copy, Clone, PartialEq)]
-enum RenderMode {
-    Normal,
-    ForDeref { mut_: bool },
-}
-
 fn render_assoc_items(
     w: &mut Buffer,
     cx: &Context,
     containing_item: &clean::Item,
     it: DefId,
     what: AssocItemRender<'_>,
+    cache: &Cache,
 ) {
-    let c = &cx.cache;
-    let v = match c.impls.get(&it) {
+    let v = match cache.impls.get(&it) {
         Some(v) => v,
         None => return,
     };
@@ -3413,6 +3310,7 @@ fn render_assoc_items(
                 false,
                 true,
                 &[],
+                cache,
             );
         }
     }
@@ -3421,11 +3319,11 @@ fn render_assoc_items(
     }
     if !traits.is_empty() {
         let deref_impl =
-            traits.iter().find(|t| t.inner_impl().trait_.def_id() == c.deref_trait_did);
+            traits.iter().find(|t| t.inner_impl().trait_.def_id() == cache.deref_trait_did);
         if let Some(impl_) = deref_impl {
             let has_deref_mut =
-                traits.iter().any(|t| t.inner_impl().trait_.def_id() == c.deref_mut_trait_did);
-            render_deref_methods(w, cx, impl_, containing_item, has_deref_mut);
+                traits.iter().any(|t| t.inner_impl().trait_.def_id() == cache.deref_mut_trait_did);
+            render_deref_methods(w, cx, impl_, containing_item, has_deref_mut, cache);
         }
 
         let (synthetic, concrete): (Vec<&&Impl>, Vec<&&Impl>) =
@@ -3434,7 +3332,7 @@ fn render_assoc_items(
             concrete.into_iter().partition(|t| t.inner_impl().blanket_impl.is_some());
 
         let mut impls = Buffer::empty_from(&w);
-        render_impls(cx, &mut impls, &concrete, containing_item);
+        render_impls(cx, &mut impls, &concrete, containing_item, cache);
         let impls = impls.into_inner();
         if !impls.is_empty() {
             write!(
@@ -3459,7 +3357,7 @@ fn render_assoc_items(
                 
\
             "
             );
-            render_impls(cx, w, &synthetic, containing_item);
+            render_impls(cx, w, &synthetic, containing_item, cache);
             write!(w, "
");
         }
 
@@ -3474,7 +3372,7 @@ fn render_assoc_items(
                 
\
             "
             );
-            render_impls(cx, w, &blanket_impl, containing_item);
+            render_impls(cx, w, &blanket_impl, containing_item, cache);
             write!(w, "
");
         }
     }
@@ -3486,6 +3384,7 @@ fn render_deref_methods(
     impl_: &Impl,
     container_item: &clean::Item,
     deref_mut: bool,
+    cache: &Cache,
 ) {
     let deref_type = impl_.inner_impl().trait_.as_ref().unwrap();
     let (target, real_target) = impl_
@@ -3503,11 +3402,11 @@ fn render_deref_methods(
     let what =
         AssocItemRender::DerefFor { trait_: deref_type, type_: real_target, deref_mut_: deref_mut };
     if let Some(did) = target.def_id() {
-        render_assoc_items(w, cx, container_item, did, what);
+        render_assoc_items(w, cx, container_item, did, what, cache);
     } else {
         if let Some(prim) = target.primitive_type() {
-            if let Some(&did) = cx.cache.primitive_locations.get(&prim) {
-                render_assoc_items(w, cx, container_item, did, what);
+            if let Some(&did) = cache.primitive_locations.get(&prim) {
+                render_assoc_items(w, cx, container_item, did, what, cache);
             }
         }
     }
@@ -3609,6 +3508,7 @@ fn render_impl(
     // This argument is used to reference same type with different paths to avoid duplication
     // in documentation pages for trait with automatic implementations like "Send" and "Sync".
     aliases: &[String],
+    cache: &Cache,
 ) {
     if render_mode == RenderMode::Normal {
         let id = cx.derive_id(match i.inner_impl().trait_ {
@@ -3651,7 +3551,7 @@ fn render_impl(
         write!(w, "", id);
         let since = i.impl_item.stability.as_ref().map(|s| &s.since[..]);
         render_stability_since_raw(w, since, outer_version);
-        if let Some(l) = cx.src_href(&i.impl_item) {
+        if let Some(l) = cx.src_href(&i.impl_item, cache) {
             write!(w, "[src]", l, "goto source code");
         }
         write!(w, "

"); @@ -3683,6 +3583,7 @@ fn render_impl( outer_version: Option<&str>, trait_: Option<&clean::Trait>, show_def_docs: bool, + cache: &Cache, ) { let item_type = item.type_(); let name = item.name.as_ref().unwrap(); @@ -3711,7 +3612,7 @@ fn render_impl( render_assoc_item(w, item, link.anchor(&id), ItemType::Impl); write!(w, ""); render_stability_since_raw(w, item.stable_since(), outer_version); - if let Some(l) = cx.src_href(item) { + if let Some(l) = cx.src_href(item, cache) { write!( w, "[src]", @@ -3733,7 +3634,7 @@ fn render_impl( assoc_const(w, item, ty, default.as_ref(), link.anchor(&id), ""); write!(w, ""); render_stability_since_raw(w, item.stable_since(), outer_version); - if let Some(l) = cx.src_href(item) { + if let Some(l) = cx.src_href(item, cache) { write!( w, "[src]", @@ -3784,7 +3685,7 @@ fn render_impl( } } - let traits = &cx.cache.traits; + let traits = &cache.traits; let trait_ = i.trait_did().map(|did| &traits[&did]); write!(w, "
"); @@ -3799,6 +3700,7 @@ fn render_impl( outer_version, trait_, show_def_docs, + cache, ); } @@ -3810,6 +3712,7 @@ fn render_impl( render_mode: RenderMode, outer_version: Option<&str>, show_def_docs: bool, + cache: &Cache, ) { for trait_item in &t.items { let n = trait_item.name.clone(); @@ -3829,6 +3732,7 @@ fn render_impl( outer_version, None, show_def_docs, + cache, ); } } @@ -3847,13 +3751,20 @@ fn render_impl( render_mode, outer_version, show_def_docs, + cache, ); } } write!(w, "
"); } -fn item_opaque_ty(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::OpaqueTy) { +fn item_opaque_ty( + w: &mut Buffer, + cx: &Context, + it: &clean::Item, + t: &clean::OpaqueTy, + cache: &Cache, +) { write!(w, "
");
     render_attributes(w, it, false);
     write!(
@@ -3871,10 +3782,16 @@ fn item_opaque_ty(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Opa
     // won't be visible anywhere in the docs. It would be nice to also show
     // associated items from the aliased type (see discussion in #32077), but
     // we need #14072 to make sense of the generics.
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn item_trait_alias(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::TraitAlias) {
+fn item_trait_alias(
+    w: &mut Buffer,
+    cx: &Context,
+    it: &clean::Item,
+    t: &clean::TraitAlias,
+    cache: &Cache,
+) {
     write!(w, "
");
     render_attributes(w, it, false);
     write!(
@@ -3892,10 +3809,10 @@ fn item_trait_alias(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::T
     // won't be visible anywhere in the docs. It would be nice to also show
     // associated items from the aliased type (see discussion in #32077), but
     // we need #14072 to make sense of the generics.
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn item_typedef(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Typedef) {
+fn item_typedef(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Typedef, cache: &Cache) {
     write!(w, "
");
     render_attributes(w, it, false);
     write!(
@@ -3913,10 +3830,10 @@ fn item_typedef(w: &mut Buffer, cx: &Context, it: &clean::Item, t: &clean::Typed
     // won't be visible anywhere in the docs. It would be nice to also show
     // associated items from the aliased type (see discussion in #32077), but
     // we need #14072 to make sense of the generics.
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn item_foreign_type(w: &mut Buffer, cx: &Context, it: &clean::Item) {
+fn item_foreign_type(w: &mut Buffer, cx: &Context, it: &clean::Item, cache: &Cache) {
     writeln!(w, "
extern {{");
     render_attributes(w, it, false);
     write!(
@@ -3928,10 +3845,10 @@ fn item_foreign_type(w: &mut Buffer, cx: &Context, it: &clean::Item) {
 
     document(w, cx, it);
 
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
-fn print_sidebar(cx: &Context, it: &clean::Item, buffer: &mut Buffer) {
+fn print_sidebar(cx: &Context, it: &clean::Item, buffer: &mut Buffer, cache: &Cache) {
     let parentlen = cx.current.len() - if it.is_mod() { 1 } else { 0 };
 
     if it.is_struct()
@@ -3966,7 +3883,7 @@ fn print_sidebar(cx: &Context, it: &clean::Item, buffer: &mut Buffer) {
     }
 
     if it.is_crate() {
-        if let Some(ref version) = cx.cache.crate_version {
+        if let Some(ref version) = cache.crate_version {
             write!(
                 buffer,
                 "
\
@@ -4603,9 +4520,9 @@ fn item_proc_macro(w: &mut Buffer, cx: &Context, it: &clean::Item, m: &clean::Pr
     document(w, cx, it)
 }
 
-fn item_primitive(w: &mut Buffer, cx: &Context, it: &clean::Item) {
+fn item_primitive(w: &mut Buffer, cx: &Context, it: &clean::Item, cache: &Cache) {
     document(w, cx, it);
-    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All)
+    render_assoc_items(w, cx, it, it.def_id, AssocItemRender::All, cache)
 }
 
 fn item_keyword(w: &mut Buffer, cx: &Context, it: &clean::Item) {
@@ -4670,7 +4587,3 @@ fn collect_paths_for_type(first_ty: clean::Type) -> Vec {
     }
     out
 }
-
-crate fn cache() -> Arc {
-    CACHE_KEY.with(|c| c.borrow().clone())
-}
diff --git a/src/librustdoc/html/sources.rs b/src/librustdoc/html/sources.rs
index e3215921f125c..aaa73b100c243 100644
--- a/src/librustdoc/html/sources.rs
+++ b/src/librustdoc/html/sources.rs
@@ -1,10 +1,11 @@
 use crate::clean;
 use crate::docfs::PathError;
+use crate::error::Error;
 use crate::fold::DocFolder;
 use crate::html::format::Buffer;
 use crate::html::highlight;
 use crate::html::layout;
-use crate::html::render::{Error, SharedContext, BASIC_KEYWORDS};
+use crate::html::render::{SharedContext, BASIC_KEYWORDS};
 use rustc_hir::def_id::LOCAL_CRATE;
 use rustc_span::source_map::FileName;
 use std::ffi::OsStr;
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
index cbf53d52ef009..65bc089faf428 100644
--- a/src/librustdoc/lib.rs
+++ b/src/librustdoc/lib.rs
@@ -63,19 +63,11 @@ mod config;
 mod core;
 mod docfs;
 mod doctree;
+#[macro_use]
+mod error;
 mod fold;
-pub mod html {
-    crate mod escape;
-    crate mod format;
-    crate mod highlight;
-    crate mod item_type;
-    crate mod layout;
-    pub mod markdown;
-    crate mod render;
-    crate mod sources;
-    crate mod static_files;
-    crate mod toc;
-}
+crate mod formats;
+pub mod html;
 mod markdown;
 mod passes;
 mod test;
@@ -85,7 +77,7 @@ mod visit_lib;
 
 struct Output {
     krate: clean::Crate,
-    renderinfo: html::render::RenderInfo,
+    renderinfo: config::RenderInfo,
     renderopts: config::RenderOptions,
 }
 
@@ -510,12 +502,19 @@ fn main_options(options: config::Options) -> i32 {
         info!("going to format");
         let (error_format, edition, debugging_options) = diag_opts;
         let diag = core::new_handler(error_format, None, &debugging_options);
-        match html::render::run(krate, renderopts, renderinfo, &diag, edition) {
+        match formats::run_format::(
+            krate, renderopts, renderinfo, &diag, edition,
+        ) {
             Ok(_) => rustc_driver::EXIT_SUCCESS,
             Err(e) => {
-                diag.struct_err(&format!("couldn't generate documentation: {}", e.error))
-                    .note(&format!("failed to create or modify \"{}\"", e.file.display()))
-                    .emit();
+                let mut msg =
+                    diag.struct_err(&format!("couldn't generate documentation: {}", e.error));
+                let file = e.file.display().to_string();
+                if file.is_empty() {
+                    msg.emit()
+                } else {
+                    msg.note(&format!("failed to create or modify \"{}\"", file)).emit()
+                }
                 rustc_driver::EXIT_FAILURE
             }
         }