3 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
4 use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX};
5 use rustc_middle::middle::privacy::AccessLevels;
6 use rustc_middle::ty::TyCtxt;
7 use rustc_span::symbol::sym;
9 use crate::clean::{self, GetDefId, ItemId, PrimitiveType};
10 use crate::config::RenderOptions;
11 use crate::fold::DocFolder;
12 use crate::formats::item_type::ItemType;
13 use crate::formats::Impl;
14 use crate::html::markdown::short_markdown_summary;
15 use crate::html::render::cache::{get_index_search_type, ExternalLocation};
16 use crate::html::render::IndexItem;
18 /// This cache is used to store information about the [`clean::Crate`] being
19 /// rendered in order to provide more useful documentation. This contains
20 /// information like all implementors of a trait, all traits a type implements,
21 /// documentation for all known traits, etc.
23 /// This structure purposefully does not implement `Clone` because it's intended
24 /// to be a fairly large and expensive structure to clone. Instead this adheres
25 /// to `Send` so it may be stored in an `Arc` instance and shared among the various
26 /// rendering threads.
29 /// Maps a type ID to all known implementations for that type. This is only
30 /// recognized for intra-crate `ResolvedPath` types, and is used to print
31 /// out extra documentation on the page of an enum/struct.
33 /// The values of the map are a list of implementations and documentation
34 /// found on that implementation.
35 crate impls: FxHashMap<DefId, Vec<Impl>>,
37 /// Maintains a mapping of local crate `DefId`s to the fully qualified name
38 /// and "short type description" of that node. This is used when generating
39 /// URLs when a type is being linked to. External paths are not located in
40 /// this map because the `External` type itself has all the information
42 crate paths: FxHashMap<DefId, (Vec<String>, ItemType)>,
44 /// Similar to `paths`, but only holds external paths. This is only used for
45 /// generating explicit hyperlinks to other crates.
46 crate external_paths: FxHashMap<DefId, (Vec<String>, ItemType)>,
48 /// Maps local `DefId`s of exported types to fully qualified paths.
49 /// Unlike 'paths', this mapping ignores any renames that occur
50 /// due to 'use' statements.
52 /// This map is used when writing out the special 'implementors'
53 /// javascript file. By using the exact path that the type
54 /// is declared with, we ensure that each path will be identical
55 /// to the path used if the corresponding type is inlined. By
56 /// doing this, we can detect duplicate impls on a trait page, and only display
57 /// the impl for the inlined type.
58 crate exact_paths: FxHashMap<DefId, Vec<String>>,
60 /// This map contains information about all known traits of this crate.
61 /// Implementations of a crate should inherit the documentation of the
62 /// parent trait if no extra documentation is specified, and default methods
63 /// should show up in documentation about trait implementations.
64 crate traits: FxHashMap<DefId, clean::TraitWithExtraInfo>,
66 /// When rendering traits, it's often useful to be able to list all
67 /// implementors of the trait, and this mapping is exactly, that: a mapping
68 /// of trait ids to the list of known implementors of the trait
69 crate implementors: FxHashMap<DefId, Vec<Impl>>,
71 /// Cache of where external crate documentation can be found.
72 crate extern_locations: FxHashMap<CrateNum, ExternalLocation>,
74 /// Cache of where documentation for primitives can be found.
75 crate primitive_locations: FxHashMap<clean::PrimitiveType, DefId>,
77 // Note that external items for which `doc(hidden)` applies to are shown as
78 // non-reachable while local items aren't. This is because we're reusing
79 // the access levels from the privacy check pass.
80 crate access_levels: AccessLevels<DefId>,
82 /// The version of the crate being documented, if given from the `--crate-version` flag.
83 crate crate_version: Option<String>,
85 /// Whether to document private items.
86 /// This is stored in `Cache` so it doesn't need to be passed through all rustdoc functions.
87 crate document_private: bool,
89 /// Crates marked with [`#[doc(masked)]`][doc_masked].
91 /// [doc_masked]: https://doc.rust-lang.org/nightly/unstable-book/language-features/doc-masked.html
92 crate masked_crates: FxHashSet<CrateNum>,
94 // Private fields only used when initially crawling a crate to build a cache
96 parent_stack: Vec<DefId>,
97 parent_is_trait_impl: bool,
100 crate search_index: Vec<IndexItem>,
102 // In rare case where a structure is defined in one module but implemented
103 // in another, if the implementing module is parsed before defining module,
104 // then the fully qualified name of the structure isn't presented in `paths`
105 // yet when its implementation methods are being indexed. Caches such methods
106 // and their parent id here and indexes them at the end of crate parsing.
107 crate orphan_impl_items: Vec<(DefId, clean::Item)>,
109 // Similarly to `orphan_impl_items`, sometimes trait impls are picked up
110 // even though the trait itself is not exported. This can happen if a trait
111 // was defined in function/expression scope, since the impl will be picked
112 // up by `collect-trait-impls` but the trait won't be scraped out in the HIR
113 // crawl. In order to prevent crashes when looking for notable traits or
114 // when gathering trait documentation on a type, hold impls here while
115 // folding and add them to the cache later on if we find the trait.
116 orphan_trait_impls: Vec<(DefId, FxHashSet<DefId>, Impl)>,
118 /// All intra-doc links resolved so far.
120 /// Links are indexed by the DefId of the item they document.
121 crate intra_doc_links: FxHashMap<ItemId, Vec<clean::ItemLink>>,
122 /// Cfg that have been hidden via #![doc(cfg_hide(...))]
123 crate hidden_cfg: FxHashSet<clean::cfg::Cfg>,
126 /// This struct is used to wrap the `cache` and `tcx` in order to run `DocFolder`.
127 struct CacheBuilder<'a, 'tcx> {
128 cache: &'a mut Cache,
133 crate fn new(access_levels: AccessLevels<DefId>, document_private: bool) -> Self {
134 Cache { access_levels, document_private, ..Cache::default() }
137 /// Populates the `Cache` with more data. The returned `Crate` will be missing some data that was
138 /// in `krate` due to the data being moved into the `Cache`.
141 mut krate: clean::Crate,
143 render_options: &RenderOptions,
145 // Crawl the crate to build various caches used for the output
146 debug!(?self.crate_version);
147 self.traits = krate.external_traits.take();
148 let RenderOptions { extern_html_root_takes_precedence, output: dst, .. } = render_options;
150 // Cache where all our extern crates are located
151 // FIXME: this part is specific to HTML so it'd be nice to remove it from the common code
152 for &e in &krate.externs {
153 let name = e.name(tcx);
155 render_options.extern_html_root_urls.get(&*name.as_str()).map(|u| &**u);
156 let location = e.location(extern_url, *extern_html_root_takes_precedence, dst, tcx);
157 self.extern_locations.insert(e.crate_num, location);
158 self.external_paths.insert(e.def_id(), (vec![name.to_string()], ItemType::Module));
161 // FIXME: avoid this clone (requires implementing Default manually)
162 self.primitive_locations = PrimitiveType::primitive_locations(tcx).clone();
163 for (prim, &def_id) in &self.primitive_locations {
164 let crate_name = tcx.crate_name(def_id.krate);
165 // Recall that we only allow primitive modules to be at the root-level of the crate.
166 // If that restriction is ever lifted, this will have to include the relative paths instead.
167 self.external_paths.insert(
169 (vec![crate_name.to_string(), prim.as_sym().to_string()], ItemType::Primitive),
173 krate = CacheBuilder { tcx, cache: self }.fold_crate(krate);
175 for (trait_did, dids, impl_) in self.orphan_trait_impls.drain(..) {
176 if self.traits.contains_key(&trait_did) {
178 self.impls.entry(did).or_default().push(impl_.clone());
187 impl<'a, 'tcx> DocFolder for CacheBuilder<'a, 'tcx> {
188 fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
189 if item.def_id.is_local() {
190 debug!("folding {} \"{:?}\", id {:?}", item.type_(), item.name, item.def_id);
193 // If this is a stripped module,
194 // we don't want it or its children in the search index.
195 let orig_stripped_mod = match *item.kind {
196 clean::StrippedItem(box clean::ModuleItem(..)) => {
197 mem::replace(&mut self.cache.stripped_mod, true)
199 _ => self.cache.stripped_mod,
202 // If the impl is from a masked crate or references something from a
203 // masked crate then remove it completely.
204 if let clean::ImplItem(ref i) = *item.kind {
205 if self.cache.masked_crates.contains(&item.def_id.krate())
208 .map_or(false, |t| self.cache.masked_crates.contains(&t.def_id().krate))
209 || i.for_.def_id().map_or(false, |d| self.cache.masked_crates.contains(&d.krate))
215 // Propagate a trait method's documentation to all implementors of the
217 if let clean::TraitItem(ref t) = *item.kind {
218 self.cache.traits.entry(item.def_id.expect_def_id()).or_insert_with(|| {
219 clean::TraitWithExtraInfo {
221 is_notable: item.attrs.has_doc_flag(sym::notable_trait),
226 // Collect all the implementors of traits.
227 if let clean::ImplItem(ref i) = *item.kind {
228 if let Some(trait_) = &i.trait_ {
229 if i.blanket_impl.is_none() {
232 .entry(trait_.def_id())
234 .push(Impl { impl_item: item.clone() });
239 // Index this method for searching later on.
240 if let Some(ref s) = item.name {
241 let (parent, is_inherent_impl_item) = match *item.kind {
242 clean::StrippedItem(..) => ((None, None), false),
243 clean::AssocConstItem(..) | clean::TypedefItem(_, true)
244 if self.cache.parent_is_trait_impl =>
246 // skip associated items in trait impls
247 ((None, None), false)
249 clean::AssocTypeItem(..)
250 | clean::TyMethodItem(..)
251 | clean::StructFieldItem(..)
252 | clean::VariantItem(..) => (
254 Some(*self.cache.parent_stack.last().expect("parent_stack is empty")),
255 Some(&self.cache.stack[..self.cache.stack.len() - 1]),
259 clean::MethodItem(..) | clean::AssocConstItem(..) => {
260 if self.cache.parent_stack.is_empty() {
261 ((None, None), false)
263 let last = self.cache.parent_stack.last().expect("parent_stack is empty 2");
265 let path = match self.cache.paths.get(&did) {
266 // The current stack not necessarily has correlation
267 // for where the type was defined. On the other
268 // hand, `paths` always has the right
269 // information if present.
276 )) => Some(&fqp[..fqp.len() - 1]),
277 Some(..) => Some(&*self.cache.stack),
280 ((Some(*last), path), true)
283 _ => ((None, Some(&*self.cache.stack)), false),
287 (parent, Some(path)) if is_inherent_impl_item || !self.cache.stripped_mod => {
288 debug_assert!(!item.is_stripped());
290 // A crate has a module at its root, containing all items,
291 // which should not be indexed. The crate-item itself is
292 // inserted later on when serializing the search-index.
293 if item.def_id.index().map_or(false, |idx| idx != CRATE_DEF_INDEX) {
294 let desc = item.doc_value().map_or_else(String::new, |x| {
295 short_markdown_summary(&x.as_str(), &item.link_names(&self.cache))
297 self.cache.search_index.push(IndexItem {
300 path: path.join("::"),
304 search_type: get_index_search_type(&item, self.tcx),
305 aliases: item.attrs.get_doc_aliases(),
309 (Some(parent), None) if is_inherent_impl_item => {
310 // We have a parent, but we don't know where they're
311 // defined yet. Wait for later to index this item.
312 self.cache.orphan_impl_items.push((parent, item.clone()));
318 // Keep track of the fully qualified path for this item.
319 let pushed = match item.name {
320 Some(n) if !n.is_empty() => {
321 self.cache.stack.push(n.to_string());
328 clean::StructItem(..)
329 | clean::EnumItem(..)
330 | clean::TypedefItem(..)
331 | clean::TraitItem(..)
332 | clean::TraitAliasItem(..)
333 | clean::FunctionItem(..)
334 | clean::ModuleItem(..)
335 | clean::ForeignFunctionItem(..)
336 | clean::ForeignStaticItem(..)
337 | clean::ConstantItem(..)
338 | clean::StaticItem(..)
339 | clean::UnionItem(..)
340 | clean::ForeignTypeItem
341 | clean::MacroItem(..)
342 | clean::ProcMacroItem(..)
343 | clean::VariantItem(..) => {
344 if !self.cache.stripped_mod {
345 // Re-exported items mean that the same id can show up twice
346 // in the rustdoc ast that we're looking at. We know,
347 // however, that a re-exported item doesn't show up in the
348 // `public_items` map, so we can skip inserting into the
349 // paths map if there was already an entry present and we're
350 // not a public item.
351 if !self.cache.paths.contains_key(&item.def_id.expect_def_id())
352 || self.cache.access_levels.is_public(item.def_id.expect_def_id())
354 self.cache.paths.insert(
355 item.def_id.expect_def_id(),
356 (self.cache.stack.clone(), item.type_()),
361 clean::PrimitiveItem(..) => {
364 .insert(item.def_id.expect_def_id(), (self.cache.stack.clone(), item.type_()));
367 clean::ExternCrateItem { .. }
368 | clean::ImportItem(..)
369 | clean::OpaqueTyItem(..)
370 | clean::ImplItem(..)
371 | clean::TyMethodItem(..)
372 | clean::MethodItem(..)
373 | clean::StructFieldItem(..)
374 | clean::AssocConstItem(..)
375 | clean::AssocTypeItem(..)
376 | clean::StrippedItem(..)
377 | clean::KeywordItem(..) => {
378 // FIXME: Do these need handling?
379 // The person writing this comment doesn't know.
380 // So would rather leave them to an expert,
381 // as at least the list is better than `_ => {}`.
385 // Maintain the parent stack
386 let orig_parent_is_trait_impl = self.cache.parent_is_trait_impl;
387 let parent_pushed = match *item.kind {
389 | clean::EnumItem(..)
390 | clean::ForeignTypeItem
391 | clean::StructItem(..)
392 | clean::UnionItem(..)
393 | clean::VariantItem(..) => {
394 self.cache.parent_stack.push(item.def_id.expect_def_id());
395 self.cache.parent_is_trait_impl = false;
398 clean::ImplItem(ref i) => {
399 self.cache.parent_is_trait_impl = i.trait_.is_some();
401 clean::ResolvedPath { did, .. } => {
402 self.cache.parent_stack.push(did);
405 clean::DynTrait(ref bounds, _)
406 | clean::BorrowedRef { type_: box clean::DynTrait(ref bounds, _), .. } => {
407 self.cache.parent_stack.push(bounds[0].trait_.def_id());
413 .and_then(|t| self.cache.primitive_locations.get(&t).cloned());
416 self.cache.parent_stack.push(did);
427 // Once we've recursively found all the generics, hoard off all the
428 // implementations elsewhere.
429 let item = self.fold_item_recur(item);
430 let ret = if let clean::Item { kind: box clean::ImplItem(ref i), .. } = item {
431 // Figure out the id of this impl. This may map to a
432 // primitive rather than always to a struct/enum.
433 // Note: matching twice to restrict the lifetime of the `i` borrow.
434 let mut dids = FxHashSet::default();
436 clean::ResolvedPath { did, .. }
437 | clean::BorrowedRef { type_: box clean::ResolvedPath { did, .. }, .. } => {
440 clean::DynTrait(ref bounds, _)
441 | clean::BorrowedRef { type_: box clean::DynTrait(ref bounds, _), .. } => {
442 dids.insert(bounds[0].trait_.def_id());
447 .and_then(|t| self.cache.primitive_locations.get(&t).cloned());
449 if let Some(did) = did {
455 if let Some(generics) = i.trait_.as_ref().and_then(|t| t.generics()) {
456 for bound in generics {
457 if let Some(did) = bound.def_id() {
462 let impl_item = Impl { impl_item: item };
463 if impl_item.trait_did().map_or(true, |d| self.cache.traits.contains_key(&d)) {
465 self.cache.impls.entry(did).or_insert(vec![]).push(impl_item.clone());
468 let trait_did = impl_item.trait_did().expect("no trait did");
469 self.cache.orphan_trait_impls.push((trait_did, dids, impl_item));
477 self.cache.stack.pop().expect("stack already empty");
480 self.cache.parent_stack.pop().expect("parent stack already empty");
482 self.cache.stripped_mod = orig_stripped_mod;
483 self.cache.parent_is_trait_impl = orig_parent_is_trait_impl;