1 use crate::clean::Attributes;
2 use crate::core::ResolverCaches;
3 use crate::passes::collect_intra_doc_links::preprocessed_markdown_links;
4 use crate::passes::collect_intra_doc_links::{Disambiguator, PreprocessedMarkdownLink};
6 use rustc_ast::visit::{self, AssocCtxt, Visitor};
7 use rustc_ast::{self as ast, ItemKind};
8 use rustc_data_structures::fx::FxHashMap;
9 use rustc_hir::def::Namespace::*;
10 use rustc_hir::def::{DefKind, Namespace, Res};
11 use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, CRATE_DEF_ID};
12 use rustc_hir::TraitCandidate;
13 use rustc_middle::ty::{DefIdTree, Visibility};
14 use rustc_resolve::{ParentScope, Resolver};
15 use rustc_session::config::Externs;
16 use rustc_session::Session;
17 use rustc_span::symbol::sym;
18 use rustc_span::{Symbol, SyntaxContext};
20 use std::collections::hash_map::Entry;
23 pub(crate) fn early_resolve_intra_doc_links(
24 resolver: &mut Resolver<'_>,
28 document_private_items: bool,
31 ParentScope::module(resolver.expect_module(CRATE_DEF_ID.to_def_id()), resolver);
32 let mut link_resolver = EarlyDocLinkResolver {
36 visited_mods: Default::default(),
37 markdown_links: Default::default(),
38 doc_link_resolutions: Default::default(),
39 traits_in_scope: Default::default(),
40 all_traits: Default::default(),
41 all_trait_impls: Default::default(),
42 all_macro_rules: Default::default(),
43 document_private_items,
46 // Overridden `visit_item` below doesn't apply to the crate root,
47 // so we have to visit its attributes and reexports separately.
48 link_resolver.resolve_doc_links_local(&krate.attrs);
49 link_resolver.process_module_children_or_reexports(CRATE_DEF_ID.to_def_id());
50 visit::walk_crate(&mut link_resolver, krate);
51 link_resolver.process_extern_impls();
53 // FIXME: somehow rustdoc is still missing crates even though we loaded all
54 // the known necessary crates. Load them all unconditionally until we find a way to fix this.
55 // DO NOT REMOVE THIS without first testing on the reproducer in
56 // https://github.com/jyn514/objr/commit/edcee7b8124abf0e4c63873e8422ff81beb11ebb
57 for (extern_name, _) in externs.iter().filter(|(_, entry)| entry.add_prelude) {
58 link_resolver.resolver.resolve_rustdoc_path(extern_name, TypeNS, parent_scope);
62 markdown_links: Some(link_resolver.markdown_links),
63 doc_link_resolutions: link_resolver.doc_link_resolutions,
64 traits_in_scope: link_resolver.traits_in_scope,
65 all_traits: Some(link_resolver.all_traits),
66 all_trait_impls: Some(link_resolver.all_trait_impls),
67 all_macro_rules: link_resolver.all_macro_rules,
71 fn doc_attrs<'a>(attrs: impl Iterator<Item = &'a ast::Attribute>) -> Attributes {
72 Attributes::from_ast_iter(attrs.map(|attr| (attr, None)), true)
75 struct EarlyDocLinkResolver<'r, 'ra> {
76 resolver: &'r mut Resolver<'ra>,
78 parent_scope: ParentScope<'ra>,
79 visited_mods: DefIdSet,
80 markdown_links: FxHashMap<String, Vec<PreprocessedMarkdownLink>>,
81 doc_link_resolutions: FxHashMap<(Symbol, Namespace, DefId), Option<Res<ast::NodeId>>>,
82 traits_in_scope: DefIdMap<Vec<TraitCandidate>>,
83 all_traits: Vec<DefId>,
84 all_trait_impls: Vec<DefId>,
85 all_macro_rules: FxHashMap<Symbol, Res<ast::NodeId>>,
86 document_private_items: bool,
89 impl<'ra> EarlyDocLinkResolver<'_, 'ra> {
90 fn add_traits_in_scope(&mut self, def_id: DefId) {
91 // Calls to `traits_in_scope` are expensive, so try to avoid them if only possible.
92 // Keys in the `traits_in_scope` cache are always module IDs.
93 if let Entry::Vacant(entry) = self.traits_in_scope.entry(def_id) {
94 let module = self.resolver.get_nearest_non_block_module(def_id);
95 let module_id = module.def_id();
96 let entry = if module_id == def_id {
98 } else if let Entry::Vacant(entry) = self.traits_in_scope.entry(module_id) {
103 if let Some(entry) = entry {
104 entry.insert(self.resolver.traits_in_scope(
106 &ParentScope::module(module, self.resolver),
107 SyntaxContext::root(),
114 /// Add traits in scope for links in impls collected by the `collect-intra-doc-links` pass.
115 /// That pass filters impls using type-based information, but we don't yet have such
116 /// information here, so we just conservatively calculate traits in scope for *all* modules
117 /// having impls in them.
118 fn process_extern_impls(&mut self) {
119 // Resolving links in already existing crates may trigger loading of new crates.
120 let mut start_cnum = 0;
122 let crates = Vec::from_iter(self.resolver.cstore().crates_untracked());
123 for &cnum in &crates[start_cnum..] {
125 Vec::from_iter(self.resolver.cstore().traits_in_crate_untracked(cnum));
126 let all_trait_impls =
127 Vec::from_iter(self.resolver.cstore().trait_impls_in_crate_untracked(cnum));
128 let all_inherent_impls =
129 Vec::from_iter(self.resolver.cstore().inherent_impls_in_crate_untracked(cnum));
130 let all_incoherent_impls = Vec::from_iter(
131 self.resolver.cstore().incoherent_impls_in_crate_untracked(cnum),
134 // Querying traits in scope is expensive so we try to prune the impl and traits lists
135 // using privacy, private traits and impls from other crates are never documented in
136 // the current crate, and links in their doc comments are not resolved.
137 for &def_id in &all_traits {
138 if self.resolver.cstore().visibility_untracked(def_id).is_public() {
139 self.resolve_doc_links_extern_impl(def_id, false);
142 for &(trait_def_id, impl_def_id, simplified_self_ty) in &all_trait_impls {
143 if self.resolver.cstore().visibility_untracked(trait_def_id).is_public()
144 && simplified_self_ty.and_then(|ty| ty.def()).map_or(true, |ty_def_id| {
145 self.resolver.cstore().visibility_untracked(ty_def_id).is_public()
148 self.resolve_doc_links_extern_impl(impl_def_id, false);
151 for (ty_def_id, impl_def_id) in all_inherent_impls {
152 if self.resolver.cstore().visibility_untracked(ty_def_id).is_public() {
153 self.resolve_doc_links_extern_impl(impl_def_id, true);
156 for impl_def_id in all_incoherent_impls {
157 self.resolve_doc_links_extern_impl(impl_def_id, true);
160 self.all_traits.extend(all_traits);
162 .extend(all_trait_impls.into_iter().map(|(_, def_id, _)| def_id));
165 if crates.len() > start_cnum {
166 start_cnum = crates.len();
173 fn resolve_doc_links_extern_impl(&mut self, def_id: DefId, is_inherent: bool) {
174 self.resolve_doc_links_extern_outer_fixme(def_id, def_id);
175 let assoc_item_def_ids = Vec::from_iter(
176 self.resolver.cstore().associated_item_def_ids_untracked(def_id, self.sess),
178 for assoc_def_id in assoc_item_def_ids {
179 if !is_inherent || self.resolver.cstore().visibility_untracked(assoc_def_id).is_public()
181 self.resolve_doc_links_extern_outer_fixme(assoc_def_id, def_id);
186 // FIXME: replace all uses with `resolve_doc_links_extern_outer` to actually resolve links, not
187 // just add traits in scope. This may be expensive and require benchmarking and optimization.
188 fn resolve_doc_links_extern_outer_fixme(&mut self, def_id: DefId, scope_id: DefId) {
189 if !self.resolver.cstore().may_have_doc_links_untracked(def_id) {
192 if let Some(parent_id) = self.resolver.opt_parent(scope_id) {
193 self.add_traits_in_scope(parent_id);
197 fn resolve_doc_links_extern_outer(&mut self, def_id: DefId, scope_id: DefId) {
198 if !self.resolver.cstore().may_have_doc_links_untracked(def_id) {
201 let attrs = Vec::from_iter(self.resolver.cstore().item_attrs_untracked(def_id, self.sess));
202 let parent_scope = ParentScope::module(
203 self.resolver.get_nearest_non_block_module(
204 self.resolver.opt_parent(scope_id).unwrap_or(scope_id),
208 self.resolve_doc_links(doc_attrs(attrs.iter()), parent_scope);
211 fn resolve_doc_links_extern_inner(&mut self, def_id: DefId) {
212 if !self.resolver.cstore().may_have_doc_links_untracked(def_id) {
215 let attrs = Vec::from_iter(self.resolver.cstore().item_attrs_untracked(def_id, self.sess));
216 let parent_scope = ParentScope::module(self.resolver.expect_module(def_id), self.resolver);
217 self.resolve_doc_links(doc_attrs(attrs.iter()), parent_scope);
220 fn resolve_doc_links_local(&mut self, attrs: &[ast::Attribute]) {
221 if !attrs.iter().any(|attr| attr.may_have_doc_links()) {
224 self.resolve_doc_links(doc_attrs(attrs.iter()), self.parent_scope);
227 fn resolve_and_cache(
231 parent_scope: &ParentScope<'ra>,
233 // FIXME: This caching may be incorrect in case of multiple `macro_rules`
234 // items with the same name in the same module.
235 self.doc_link_resolutions
236 .entry((Symbol::intern(path_str), ns, parent_scope.module.def_id()))
237 .or_insert_with_key(|(path, ns, _)| {
238 self.resolver.resolve_rustdoc_path(path.as_str(), *ns, *parent_scope)
243 fn resolve_doc_links(&mut self, attrs: Attributes, parent_scope: ParentScope<'ra>) {
244 let mut need_traits_in_scope = false;
245 for (doc_module, doc) in attrs.prepare_to_doc_link_resolution() {
246 assert_eq!(doc_module, None);
247 let mut tmp_links = mem::take(&mut self.markdown_links);
249 tmp_links.entry(doc).or_insert_with_key(|doc| preprocessed_markdown_links(doc));
250 for PreprocessedMarkdownLink(pp_link, _) in links {
251 if let Ok(pinfo) = pp_link {
252 // The logic here is a conservative approximation for path resolution in
253 // `resolve_with_disambiguator`.
254 if let Some(ns) = pinfo.disambiguator.map(Disambiguator::ns) {
255 if self.resolve_and_cache(&pinfo.path_str, ns, &parent_scope) {
260 // Resolve all namespaces due to no disambiguator or for diagnostics.
261 let mut any_resolved = false;
262 let mut need_assoc = false;
263 for ns in [TypeNS, ValueNS, MacroNS] {
264 if self.resolve_and_cache(&pinfo.path_str, ns, &parent_scope) {
266 } else if ns != MacroNS {
271 // Resolve all prefixes for type-relative resolution or for diagnostics.
272 if need_assoc || !any_resolved {
273 let mut path = &pinfo.path_str[..];
274 while let Some(idx) = path.rfind("::") {
276 need_traits_in_scope = true;
277 for ns in [TypeNS, ValueNS, MacroNS] {
278 self.resolve_and_cache(path, ns, &parent_scope);
284 self.markdown_links = tmp_links;
287 if need_traits_in_scope {
288 self.add_traits_in_scope(parent_scope.module.def_id());
292 /// When reexports are inlined, they are replaced with item which they refer to, those items
293 /// may have links in their doc comments, those links are resolved at the item definition site,
294 /// so we need to know traits in scope at that definition site.
295 fn process_module_children_or_reexports(&mut self, module_id: DefId) {
296 if !self.visited_mods.insert(module_id) {
297 return; // avoid infinite recursion
300 for child in self.resolver.module_children_or_reexports(module_id) {
301 // This condition should give a superset of `denied` from `fn clean_use_statement`.
302 if child.vis.is_public()
303 || self.document_private_items
304 && child.vis != Visibility::Restricted(module_id)
305 && module_id.is_local()
307 if let Some(def_id) = child.res.opt_def_id() && !def_id.is_local() {
308 let scope_id = match child.res {
309 Res::Def(DefKind::Variant, ..) => self.resolver.parent(def_id),
312 self.resolve_doc_links_extern_outer(def_id, scope_id); // Outer attribute scope
313 if let Res::Def(DefKind::Mod, ..) = child.res {
314 self.resolve_doc_links_extern_inner(def_id); // Inner attribute scope
316 // `DefKind::Trait`s are processed in `process_extern_impls`.
317 if let Res::Def(DefKind::Mod | DefKind::Enum, ..) = child.res {
318 self.process_module_children_or_reexports(def_id);
320 if let Res::Def(DefKind::Struct | DefKind::Union | DefKind::Variant, _) =
323 let field_def_ids = Vec::from_iter(
326 .associated_item_def_ids_untracked(def_id, self.sess),
328 for field_def_id in field_def_ids {
329 self.resolve_doc_links_extern_outer(field_def_id, scope_id);
338 impl Visitor<'_> for EarlyDocLinkResolver<'_, '_> {
339 fn visit_item(&mut self, item: &ast::Item) {
340 self.resolve_doc_links_local(&item.attrs); // Outer attribute scope
341 if let ItemKind::Mod(..) = item.kind {
342 let module_def_id = self.resolver.local_def_id(item.id).to_def_id();
343 let module = self.resolver.expect_module(module_def_id);
344 let old_module = mem::replace(&mut self.parent_scope.module, module);
345 let old_macro_rules = self.parent_scope.macro_rules;
346 self.resolve_doc_links_local(&item.attrs); // Inner attribute scope
347 self.process_module_children_or_reexports(module_def_id);
348 visit::walk_item(self, item);
352 .all(|attr| !attr.has_name(sym::macro_use) && !attr.has_name(sym::macro_escape))
354 self.parent_scope.macro_rules = old_macro_rules;
356 self.parent_scope.module = old_module;
359 ItemKind::Trait(..) => {
360 self.all_traits.push(self.resolver.local_def_id(item.id).to_def_id());
362 ItemKind::Impl(box ast::Impl { of_trait: Some(..), .. }) => {
363 self.all_trait_impls.push(self.resolver.local_def_id(item.id).to_def_id());
365 ItemKind::MacroDef(macro_def) if macro_def.macro_rules => {
366 let (macro_rules_scope, res) =
367 self.resolver.macro_rules_scope(self.resolver.local_def_id(item.id));
368 self.parent_scope.macro_rules = macro_rules_scope;
369 self.all_macro_rules.insert(item.ident.name, res);
373 visit::walk_item(self, item);
377 fn visit_assoc_item(&mut self, item: &ast::AssocItem, ctxt: AssocCtxt) {
378 self.resolve_doc_links_local(&item.attrs);
379 visit::walk_assoc_item(self, item, ctxt)
382 fn visit_foreign_item(&mut self, item: &ast::ForeignItem) {
383 self.resolve_doc_links_local(&item.attrs);
384 visit::walk_foreign_item(self, item)
387 fn visit_variant(&mut self, v: &ast::Variant) {
388 self.resolve_doc_links_local(&v.attrs);
389 visit::walk_variant(self, v)
392 fn visit_field_def(&mut self, field: &ast::FieldDef) {
393 self.resolve_doc_links_local(&field.attrs);
394 visit::walk_field_def(self, field)
397 fn visit_block(&mut self, block: &ast::Block) {
398 let old_macro_rules = self.parent_scope.macro_rules;
399 visit::walk_block(self, block);
400 self.parent_scope.macro_rules = old_macro_rules;
403 // NOTE: if doc-comments are ever allowed on other nodes (e.g. function parameters),
404 // then this will have to implement other visitor methods too.