src/librustdoc/core.rs - third_party/rust - Git at Google

 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
 use rustc_data_structures::sync::Lrc;
 use rustc_data_structures::unord::UnordSet;
 use rustc_errors::emitter::{stderr_destination, DynEmitter, HumanEmitter};
 use rustc_errors::json::JsonEmitter;
 use rustc_errors::{codes::*, ErrorGuaranteed, TerminalUrl};
 use rustc_feature::UnstableFeatures;
 use rustc_hir::def::Res;
 use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, LocalDefId};
 use rustc_hir::intravisit::{self, Visitor};
 use rustc_hir::{HirId, Path};
 use rustc_interface::interface;
 use rustc_lint::{late_lint_mod, MissingDoc};
 use rustc_middle::hir::nested_filter;
 use rustc_middle::ty::{ParamEnv, Ty, TyCtxt};
 use rustc_session::config::{self, CrateType, ErrorOutputType, ResolveDocLinks};
 use rustc_session::lint;
 use rustc_session::Session;
 use rustc_span::symbol::sym;
 use rustc_span::{source_map, Span};

 use std::cell::RefCell;
 use std::io;
 use std::mem;
 use std::rc::Rc;
 use std::sync::LazyLock;
 use std::sync::{atomic::AtomicBool, Arc};

 use crate::clean::inline::build_external_trait;
 use crate::clean::{self, ItemId};
 use crate::config::{Options as RustdocOptions, OutputFormat, RenderOptions};
 use crate::formats::cache::Cache;
 use crate::passes::{self, Condition::*};

 pub(crate) use rustc_session::config::{Input, Options, UnstableOptions};

 pub(crate) struct DocContext<'tcx> {
     pub(crate) tcx: TyCtxt<'tcx>,
     /// Used for normalization.
     ///
     /// Most of this logic is copied from rustc_lint::late.
     pub(crate) param_env: ParamEnv<'tcx>,
     /// Later on moved through `clean::Crate` into `cache`
     pub(crate) external_traits: Rc<RefCell<FxHashMap<DefId, clean::Trait>>>,
     /// Used while populating `external_traits` to ensure we don't process the same trait twice at
     /// the same time.
     pub(crate) active_extern_traits: DefIdSet,
     /// The current set of parameter instantiations for expanding type aliases at the HIR level.
     ///
     /// Maps from the `DefId` of a lifetime or type parameter to the
     /// generic argument it's currently instantiated to in this context.
     // FIXME(#82852): We don't record const params since we don't visit const exprs at all and
     // therefore wouldn't use the corresp. generic arg anyway. Add support for them.
     pub(crate) args: DefIdMap<clean::GenericArg>,
     pub(crate) current_type_aliases: DefIdMap<usize>,
     /// Table synthetic type parameter for `impl Trait` in argument position -> bounds
     pub(crate) impl_trait_bounds: FxHashMap<ImplTraitParam, Vec<clean::GenericBound>>,
     /// Auto-trait or blanket impls processed so far, as `(self_ty, trait_def_id)`.
     // FIXME(eddyb) make this a `ty::TraitRef<'tcx>` set.
     pub(crate) generated_synthetics: FxHashSet<(Ty<'tcx>, DefId)>,
     pub(crate) auto_traits: Vec<DefId>,
     /// The options given to rustdoc that could be relevant to a pass.
     pub(crate) render_options: RenderOptions,
     /// This same cache is used throughout rustdoc, including in [`crate::html::render`].
     pub(crate) cache: Cache,
     /// Used by [`clean::inline`] to tell if an item has already been inlined.
     pub(crate) inlined: FxHashSet<ItemId>,
     /// Used by `calculate_doc_coverage`.
     pub(crate) output_format: OutputFormat,
     /// Used by `strip_private`.
     pub(crate) show_coverage: bool,
 }

 impl<'tcx> DocContext<'tcx> {
     pub(crate) fn sess(&self) -> &'tcx Session {
         self.tcx.sess
     }

     pub(crate) fn with_param_env<T, F: FnOnce(&mut Self) -> T>(
         &mut self,
         def_id: DefId,
         f: F,
     ) -> T {
         let old_param_env = mem::replace(&mut self.param_env, self.tcx.param_env(def_id));
         let ret = f(self);
         self.param_env = old_param_env;
         ret
     }

     /// Call the closure with the given parameters set as
     /// the generic parameters for a type alias' RHS.
     pub(crate) fn enter_alias<F, R>(
         &mut self,
         args: DefIdMap<clean::GenericArg>,
         def_id: DefId,
         f: F,
     ) -> R
     where
         F: FnOnce(&mut Self) -> R,
     {
         let old_args = mem::replace(&mut self.args, args);
         *self.current_type_aliases.entry(def_id).or_insert(0) += 1;
         let r = f(self);
         self.args = old_args;
         if let Some(count) = self.current_type_aliases.get_mut(&def_id) {
             *count -= 1;
             if *count == 0 {
                 self.current_type_aliases.remove(&def_id);
             }
         }
         r
     }

     /// Like `tcx.local_def_id_to_hir_id()`, but skips calling it on fake DefIds.
     /// (This avoids a slice-index-out-of-bounds panic.)
     pub(crate) fn as_local_hir_id(tcx: TyCtxt<'_>, item_id: ItemId) -> Option<HirId> {
         match item_id {
             ItemId::DefId(real_id) => {
                 real_id.as_local().map(|def_id| tcx.local_def_id_to_hir_id(def_id))
             }
             // FIXME: Can this be `Some` for `Auto` or `Blanket`?
             _ => None,
         }
     }
 }

 /// Creates a new `DiagCtxt` that can be used to emit warnings and errors.
 ///
 /// If the given `error_format` is `ErrorOutputType::Json` and no `SourceMap` is given, a new one
 /// will be created for the `DiagCtxt`.
 pub(crate) fn new_dcx(
     error_format: ErrorOutputType,
     source_map: Option<Lrc<source_map::SourceMap>>,
     diagnostic_width: Option<usize>,
     unstable_opts: &UnstableOptions,
 ) -> rustc_errors::DiagCtxt {
     let fallback_bundle = rustc_errors::fallback_fluent_bundle(
         rustc_driver::DEFAULT_LOCALE_RESOURCES.to_vec(),
         false,
     );
     let emitter: Box<DynEmitter> = match error_format {
         ErrorOutputType::HumanReadable(kind) => {
             let (short, color_config) = kind.unzip();
             Box::new(
                 HumanEmitter::new(stderr_destination(color_config), fallback_bundle)
                     .sm(source_map.map(|sm| sm as _))
                     .short_message(short)
                     .teach(unstable_opts.teach)
                     .diagnostic_width(diagnostic_width)
                     .track_diagnostics(unstable_opts.track_diagnostics)
                     .ui_testing(unstable_opts.ui_testing),
             )
         }
         ErrorOutputType::Json { pretty, json_rendered } => {
             let source_map = source_map.unwrap_or_else(|| {
                 Lrc::new(source_map::SourceMap::new(source_map::FilePathMapping::empty()))
             });
             Box::new(
                 JsonEmitter::new(
                     Box::new(io::BufWriter::new(io::stderr())),
                     source_map,
                     fallback_bundle,
                     pretty,
                     json_rendered,
                 )
                 .ui_testing(unstable_opts.ui_testing)
                 .diagnostic_width(diagnostic_width)
                 .track_diagnostics(unstable_opts.track_diagnostics)
                 .terminal_url(TerminalUrl::No),
             )
         }
     };

     rustc_errors::DiagCtxt::new(emitter).with_flags(unstable_opts.dcx_flags(true))
 }

 /// Parse, resolve, and typecheck the given crate.
 pub(crate) fn create_config(
     RustdocOptions {
         input,
         crate_name,
         proc_macro_crate,
         error_format,
         diagnostic_width,
         libs,
         externs,
         mut cfgs,
         check_cfgs,
         codegen_options,
         unstable_opts,
         target,
         edition,
         maybe_sysroot,
         lint_opts,
         describe_lints,
         lint_cap,
         scrape_examples_options,
         expanded_args,
         ..
     }: RustdocOptions,
     RenderOptions { document_private, .. }: &RenderOptions,
     using_internal_features: Arc<AtomicBool>,
 ) -> rustc_interface::Config {
     // Add the doc cfg into the doc build.
     cfgs.push("doc".to_string());

     let input = Input::File(input);

     // By default, rustdoc ignores all lints.
     // Specifically unblock lints relevant to documentation or the lint machinery itself.
     let mut lints_to_show = vec![
         // it's unclear whether these should be part of rustdoc directly (#77364)
         rustc_lint::builtin::MISSING_DOCS.name.to_string(),
         rustc_lint::builtin::INVALID_DOC_ATTRIBUTES.name.to_string(),
         // these are definitely not part of rustdoc, but we want to warn on them anyway.
         rustc_lint::builtin::RENAMED_AND_REMOVED_LINTS.name.to_string(),
         rustc_lint::builtin::UNKNOWN_LINTS.name.to_string(),
         rustc_lint::builtin::UNEXPECTED_CFGS.name.to_string(),
         // this lint is needed to support `#[expect]` attributes
         rustc_lint::builtin::UNFULFILLED_LINT_EXPECTATIONS.name.to_string(),
     ];
     lints_to_show.extend(crate::lint::RUSTDOC_LINTS.iter().map(|lint| lint.name.to_string()));

     let (lint_opts, lint_caps) = crate::lint::init_lints(lints_to_show, lint_opts, |lint| {
         Some((lint.name_lower(), lint::Allow))
     });

     let crate_types =
         if proc_macro_crate { vec![CrateType::ProcMacro] } else { vec![CrateType::Rlib] };
     let resolve_doc_links =
         if *document_private { ResolveDocLinks::All } else { ResolveDocLinks::Exported };
     let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false);
     // plays with error output here!
     let sessopts = config::Options {
         maybe_sysroot,
         search_paths: libs,
         crate_types,
         lint_opts,
         lint_cap,
         cg: codegen_options,
         externs,
         target_triple: target,
         unstable_features: UnstableFeatures::from_environment(crate_name.as_deref()),
         actually_rustdoc: true,
         resolve_doc_links,
         unstable_opts,
         error_format,
         diagnostic_width,
         edition,
         describe_lints,
         crate_name,
         test,
         ..Options::default()
     };

     interface::Config {
         opts: sessopts,
         crate_cfg: cfgs,
         crate_check_cfg: check_cfgs,
         input,
         output_file: None,
         output_dir: None,
         file_loader: None,
         locale_resources: rustc_driver::DEFAULT_LOCALE_RESOURCES,
         lint_caps,
         psess_created: None,
         hash_untracked_state: None,
         register_lints: Some(Box::new(crate::lint::register_lints)),
         override_queries: Some(|_sess, providers| {
             // We do not register late module lints, so this only runs `MissingDoc`.
             // Most lints will require typechecking, so just don't run them.
             providers.lint_mod = |tcx, module_def_id| late_lint_mod(tcx, module_def_id, MissingDoc);
             // hack so that `used_trait_imports` won't try to call typeck
             providers.used_trait_imports = |_, _| {
                 static EMPTY_SET: LazyLock<UnordSet<LocalDefId>> = LazyLock::new(UnordSet::default);
                 &EMPTY_SET
             };
             // In case typeck does end up being called, don't ICE in case there were name resolution errors
             providers.typeck = move |tcx, def_id| {
                 // Closures' tables come from their outermost function,
                 // as they are part of the same "inference environment".
                 // This avoids emitting errors for the parent twice (see similar code in `typeck_with_fallback`)
                 let typeck_root_def_id = tcx.typeck_root_def_id(def_id.to_def_id()).expect_local();
                 if typeck_root_def_id != def_id {
                     return tcx.typeck(typeck_root_def_id);
                 }

                 let hir = tcx.hir();
                 let body = hir.body(hir.body_owned_by(def_id));
                 debug!("visiting body for {def_id:?}");
                 EmitIgnoredResolutionErrors::new(tcx).visit_body(body);
                 (rustc_interface::DEFAULT_QUERY_PROVIDERS.typeck)(tcx, def_id)
             };
         }),
         make_codegen_backend: None,
         registry: rustc_driver::diagnostics_registry(),
         ice_file: None,
         using_internal_features,
         expanded_args,
     }
 }

 pub(crate) fn run_global_ctxt(
     tcx: TyCtxt<'_>,
     show_coverage: bool,
     render_options: RenderOptions,
     output_format: OutputFormat,
 ) -> Result<(clean::Crate, RenderOptions, Cache), ErrorGuaranteed> {
     // Certain queries assume that some checks were run elsewhere
     // (see https://github.com/rust-lang/rust/pull/73566#issuecomment-656954425),
     // so type-check everything other than function bodies in this crate before running lints.

     // NOTE: this does not call `tcx.analysis()` so that we won't
     // typeck function bodies or run the default rustc lints.
     // (see `override_queries` in the `config`)

     // NOTE: These are copy/pasted from typeck/lib.rs and should be kept in sync with those changes.
     let _ = tcx.sess.time("wf_checking", || {
         tcx.hir().try_par_for_each_module(|module| tcx.ensure().check_mod_type_wf(module))
     });

     if let Some(guar) = tcx.dcx().has_errors() {
         return Err(guar);
     }

     tcx.sess.time("missing_docs", || rustc_lint::check_crate(tcx));
     tcx.sess.time("check_mod_attrs", || {
         tcx.hir().for_each_module(|module| tcx.ensure().check_mod_attrs(module))
     });
     rustc_passes::stability::check_unused_or_stable_features(tcx);

     let auto_traits =
         tcx.all_traits().filter(|&trait_def_id| tcx.trait_is_auto(trait_def_id)).collect();

     let mut ctxt = DocContext {
         tcx,
         param_env: ParamEnv::empty(),
         external_traits: Default::default(),
         active_extern_traits: Default::default(),
         args: Default::default(),
         current_type_aliases: Default::default(),
         impl_trait_bounds: Default::default(),
         generated_synthetics: Default::default(),
         auto_traits,
         cache: Cache::new(render_options.document_private, render_options.document_hidden),
         inlined: FxHashSet::default(),
         output_format,
         render_options,
         show_coverage,
     };

     for cnum in tcx.crates(()) {
         crate::visit_lib::lib_embargo_visit_item(&mut ctxt, cnum.as_def_id());
     }

     // Small hack to force the Sized trait to be present.
     //
     // Note that in case of `#![no_core]`, the trait is not available.
     if let Some(sized_trait_did) = ctxt.tcx.lang_items().sized_trait() {
         let sized_trait = build_external_trait(&mut ctxt, sized_trait_did);
         ctxt.external_traits.borrow_mut().insert(sized_trait_did, sized_trait);
     }

     debug!("crate: {:?}", tcx.hir().krate());

     let mut krate = tcx.sess.time("clean_crate", || clean::krate(&mut ctxt));

     if krate.module.doc_value().is_empty() {
         let help = format!(
             "The following guide may be of use:\n\
             {}/rustdoc/how-to-write-documentation.html",
             crate::DOC_RUST_LANG_ORG_CHANNEL
         );
         tcx.node_lint(
             crate::lint::MISSING_CRATE_LEVEL_DOCS,
             DocContext::as_local_hir_id(tcx, krate.module.item_id).unwrap(),
             "no documentation found for this crate's top-level module",
             |lint| {
                 lint.help(help);
             },
         );
     }

     fn report_deprecated_attr(name: &str, dcx: &rustc_errors::DiagCtxt, sp: Span) {
         let mut msg =
             dcx.struct_span_warn(sp, format!("the `#![doc({name})]` attribute is deprecated"));
         msg.note(
             "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
             for more information",
         );

         if name == "no_default_passes" {
             msg.help("`#![doc(no_default_passes)]` no longer functions; you may want to use `#![doc(document_private_items)]`");
         } else if name.starts_with("passes") {
             msg.help("`#![doc(passes = \"...\")]` no longer functions; you may want to use `#![doc(document_private_items)]`");
         } else if name.starts_with("plugins") {
             msg.warn("`#![doc(plugins = \"...\")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>");
         }

         msg.emit();
     }

     // Process all of the crate attributes, extracting plugin metadata along
     // with the passes which we are supposed to run.
     for attr in krate.module.attrs.lists(sym::doc) {
         let dcx = ctxt.sess().dcx();

         let name = attr.name_or_empty();
         // `plugins = "..."`, `no_default_passes`, and `passes = "..."` have no effect
         if attr.is_word() && name == sym::no_default_passes {
             report_deprecated_attr("no_default_passes", dcx, attr.span());
         } else if attr.value_str().is_some() {
             match name {
                 sym::passes => {
                     report_deprecated_attr("passes = \"...\"", dcx, attr.span());
                 }
                 sym::plugins => {
                     report_deprecated_attr("plugins = \"...\"", dcx, attr.span());
                 }
                 _ => (),
             }
         }

         if attr.is_word() && name == sym::document_private_items {
             ctxt.render_options.document_private = true;
         }
     }

     info!("Executing passes");

     for p in passes::defaults(show_coverage) {
         let run = match p.condition {
             Always => true,
             WhenDocumentPrivate => ctxt.render_options.document_private,
             WhenNotDocumentPrivate => !ctxt.render_options.document_private,
             WhenNotDocumentHidden => !ctxt.render_options.document_hidden,
         };
         if run {
             debug!("running pass {}", p.pass.name);
             krate = tcx.sess.time(p.pass.name, || (p.pass.run)(krate, &mut ctxt));
         }
     }

     tcx.sess.time("check_lint_expectations", || tcx.check_expectations(Some(sym::rustdoc)));

     if let Some(guar) = tcx.dcx().has_errors() {
         return Err(guar);
     }

     krate = tcx.sess.time("create_format_cache", || Cache::populate(&mut ctxt, krate));

     Ok((krate, ctxt.render_options, ctxt.cache))
 }

 /// Due to <https://github.com/rust-lang/rust/pull/73566>,
 /// the name resolution pass may find errors that are never emitted.
 /// If typeck is called after this happens, then we'll get an ICE:
 /// 'Res::Error found but not reported'. To avoid this, emit the errors now.
 struct EmitIgnoredResolutionErrors<'tcx> {
     tcx: TyCtxt<'tcx>,
 }

 impl<'tcx> EmitIgnoredResolutionErrors<'tcx> {
     fn new(tcx: TyCtxt<'tcx>) -> Self {
         Self { tcx }
     }
 }

 impl<'tcx> Visitor<'tcx> for EmitIgnoredResolutionErrors<'tcx> {
     type NestedFilter = nested_filter::OnlyBodies;

     fn nested_visit_map(&mut self) -> Self::Map {
         // We need to recurse into nested closures,
         // since those will fallback to the parent for type checking.
         self.tcx.hir()
     }

     fn visit_path(&mut self, path: &Path<'tcx>, _id: HirId) {
         debug!("visiting path {path:?}");
         if path.res == Res::Err {
             // We have less context here than in rustc_resolve,
             // so we can only emit the name and span.
             // However we can give a hint that rustc_resolve will have more info.
             let label = format!(
                 "could not resolve path `{}`",
                 path.segments
                     .iter()
                     .map(|segment| segment.ident.as_str())
                     .intersperse("::")
                     .collect::<String>()
             );
             rustc_errors::struct_span_code_err!(
                 self.tcx.dcx(),
                 path.span,
                 E0433,
                 "failed to resolve: {label}",
             )
             .with_span_label(path.span, label)
             .with_note("this error was originally ignored because you are running `rustdoc`")
             .with_note("try running again with `rustc` or `cargo check` and you may get a more detailed error")
             .emit();
         }
         // We could have an outer resolution that succeeded,
         // but with generic parameters that failed.
         // Recurse into the segments so we catch those too.
         intravisit::walk_path(self, path);
     }
 }

 /// `DefId` or parameter index (`ty::ParamTy.index`) of a synthetic type parameter
 /// for `impl Trait` in argument position.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub(crate) enum ImplTraitParam {
     DefId(DefId),
     ParamIndex(u32),
 }

 impl From<DefId> for ImplTraitParam {
     fn from(did: DefId) -> Self {
         ImplTraitParam::DefId(did)
     }
 }

 impl From<u32> for ImplTraitParam {
     fn from(idx: u32) -> Self {
         ImplTraitParam::ParamIndex(idx)
     }
 }
	use rustc_data_structures::fx::{FxHashMap, FxHashSet};
	use rustc_data_structures::sync::Lrc;
	use rustc_data_structures::unord::UnordSet;
	use rustc_errors::emitter::{stderr_destination, DynEmitter, HumanEmitter};
	use rustc_errors::json::JsonEmitter;
	use rustc_errors::{codes::*, ErrorGuaranteed, TerminalUrl};
	use rustc_feature::UnstableFeatures;
	use rustc_hir::def::Res;
	use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, LocalDefId};
	use rustc_hir::intravisit::{self, Visitor};
	use rustc_hir::{HirId, Path};
	use rustc_interface::interface;
	use rustc_lint::{late_lint_mod, MissingDoc};
	use rustc_middle::hir::nested_filter;
	use rustc_middle::ty::{ParamEnv, Ty, TyCtxt};
	use rustc_session::config::{self, CrateType, ErrorOutputType, ResolveDocLinks};
	use rustc_session::lint;
	use rustc_session::Session;
	use rustc_span::symbol::sym;
	use rustc_span::{source_map, Span};

	use std::cell::RefCell;
	use std::io;
	use std::mem;
	use std::rc::Rc;
	use std::sync::LazyLock;
	use std::sync::{atomic::AtomicBool, Arc};

	use crate::clean::inline::build_external_trait;
	use crate::clean::{self, ItemId};
	use crate::config::{Options as RustdocOptions, OutputFormat, RenderOptions};
	use crate::formats::cache::Cache;
	use crate::passes::{self, Condition::*};

	pub(crate) use rustc_session::config::{Input, Options, UnstableOptions};

	pub(crate) struct DocContext<'tcx> {
	pub(crate) tcx: TyCtxt<'tcx>,
	/// Used for normalization.
	///
	/// Most of this logic is copied from rustc_lint::late.
	pub(crate) param_env: ParamEnv<'tcx>,
	/// Later on moved through `clean::Crate` into `cache`
	pub(crate) external_traits: Rc<RefCell<FxHashMap<DefId, clean::Trait>>>,
	/// Used while populating `external_traits` to ensure we don't process the same trait twice at
	/// the same time.
	pub(crate) active_extern_traits: DefIdSet,
	/// The current set of parameter instantiations for expanding type aliases at the HIR level.
	///
	/// Maps from the `DefId` of a lifetime or type parameter to the
	/// generic argument it's currently instantiated to in this context.
	// FIXME(#82852): We don't record const params since we don't visit const exprs at all and
	// therefore wouldn't use the corresp. generic arg anyway. Add support for them.
	pub(crate) args: DefIdMap<clean::GenericArg>,
	pub(crate) current_type_aliases: DefIdMap<usize>,
	/// Table synthetic type parameter for `impl Trait` in argument position -> bounds
	pub(crate) impl_trait_bounds: FxHashMap<ImplTraitParam, Vec<clean::GenericBound>>,
	/// Auto-trait or blanket impls processed so far, as `(self_ty, trait_def_id)`.
	// FIXME(eddyb) make this a `ty::TraitRef<'tcx>` set.
	pub(crate) generated_synthetics: FxHashSet<(Ty<'tcx>, DefId)>,
	pub(crate) auto_traits: Vec<DefId>,
	/// The options given to rustdoc that could be relevant to a pass.
	pub(crate) render_options: RenderOptions,
	/// This same cache is used throughout rustdoc, including in [`crate::html::render`].
	pub(crate) cache: Cache,
	/// Used by [`clean::inline`] to tell if an item has already been inlined.
	pub(crate) inlined: FxHashSet<ItemId>,
	/// Used by `calculate_doc_coverage`.
	pub(crate) output_format: OutputFormat,
	/// Used by `strip_private`.
	pub(crate) show_coverage: bool,
	}

	impl<'tcx> DocContext<'tcx> {
	pub(crate) fn sess(&self) -> &'tcx Session {
	self.tcx.sess
	}

	pub(crate) fn with_param_env<T, F: FnOnce(&mut Self) -> T>(
	&mut self,
	def_id: DefId,
	f: F,
	) -> T {
	let old_param_env = mem::replace(&mut self.param_env, self.tcx.param_env(def_id));
	let ret = f(self);
	self.param_env = old_param_env;
	ret
	}

	/// Call the closure with the given parameters set as
	/// the generic parameters for a type alias' RHS.
	pub(crate) fn enter_alias<F, R>(
	&mut self,
	args: DefIdMap<clean::GenericArg>,
	def_id: DefId,
	f: F,
	) -> R
	where
	F: FnOnce(&mut Self) -> R,
	{
	let old_args = mem::replace(&mut self.args, args);
	*self.current_type_aliases.entry(def_id).or_insert(0) += 1;
	let r = f(self);
	self.args = old_args;
	if let Some(count) = self.current_type_aliases.get_mut(&def_id) {
	*count -= 1;
	if *count == 0 {
	self.current_type_aliases.remove(&def_id);
	}
	}
	r
	}

	/// Like `tcx.local_def_id_to_hir_id()`, but skips calling it on fake DefIds.
	/// (This avoids a slice-index-out-of-bounds panic.)
	pub(crate) fn as_local_hir_id(tcx: TyCtxt<'_>, item_id: ItemId) -> Option<HirId> {
	match item_id {
	ItemId::DefId(real_id) => {
	real_id.as_local().map(\|def_id\| tcx.local_def_id_to_hir_id(def_id))
	}
	// FIXME: Can this be `Some` for `Auto` or `Blanket`?
	_ => None,
	}
	}
	}

	/// Creates a new `DiagCtxt` that can be used to emit warnings and errors.
	///
	/// If the given `error_format` is `ErrorOutputType::Json` and no `SourceMap` is given, a new one
	/// will be created for the `DiagCtxt`.
	pub(crate) fn new_dcx(
	error_format: ErrorOutputType,
	source_map: Option<Lrc<source_map::SourceMap>>,
	diagnostic_width: Option<usize>,
	unstable_opts: &UnstableOptions,
	) -> rustc_errors::DiagCtxt {
	let fallback_bundle = rustc_errors::fallback_fluent_bundle(
	rustc_driver::DEFAULT_LOCALE_RESOURCES.to_vec(),
	false,
	);
	let emitter: Box<DynEmitter> = match error_format {
	ErrorOutputType::HumanReadable(kind) => {
	let (short, color_config) = kind.unzip();
	Box::new(
	HumanEmitter::new(stderr_destination(color_config), fallback_bundle)
	.sm(source_map.map(\|sm\| sm as _))
	.short_message(short)
	.teach(unstable_opts.teach)
	.diagnostic_width(diagnostic_width)
	.track_diagnostics(unstable_opts.track_diagnostics)
	.ui_testing(unstable_opts.ui_testing),
	)
	}
	ErrorOutputType::Json { pretty, json_rendered } => {
	let source_map = source_map.unwrap_or_else(\|\| {
	Lrc::new(source_map::SourceMap::new(source_map::FilePathMapping::empty()))
	});
	Box::new(
	JsonEmitter::new(
	Box::new(io::BufWriter::new(io::stderr())),
	source_map,
	fallback_bundle,
	pretty,
	json_rendered,
	)
	.ui_testing(unstable_opts.ui_testing)
	.diagnostic_width(diagnostic_width)
	.track_diagnostics(unstable_opts.track_diagnostics)
	.terminal_url(TerminalUrl::No),
	)
	}
	};

	rustc_errors::DiagCtxt::new(emitter).with_flags(unstable_opts.dcx_flags(true))
	}

	/// Parse, resolve, and typecheck the given crate.
	pub(crate) fn create_config(
	RustdocOptions {
	input,
	crate_name,
	proc_macro_crate,
	error_format,
	diagnostic_width,
	libs,
	externs,
	mut cfgs,
	check_cfgs,
	codegen_options,
	unstable_opts,
	target,
	edition,
	maybe_sysroot,
	lint_opts,
	describe_lints,
	lint_cap,
	scrape_examples_options,
	expanded_args,
	..
	}: RustdocOptions,
	RenderOptions { document_private, .. }: &RenderOptions,
	using_internal_features: Arc<AtomicBool>,
	) -> rustc_interface::Config {
	// Add the doc cfg into the doc build.
	cfgs.push("doc".to_string());

	let input = Input::File(input);

	// By default, rustdoc ignores all lints.
	// Specifically unblock lints relevant to documentation or the lint machinery itself.
	let mut lints_to_show = vec![
	// it's unclear whether these should be part of rustdoc directly (#77364)
	rustc_lint::builtin::MISSING_DOCS.name.to_string(),
	rustc_lint::builtin::INVALID_DOC_ATTRIBUTES.name.to_string(),
	// these are definitely not part of rustdoc, but we want to warn on them anyway.
	rustc_lint::builtin::RENAMED_AND_REMOVED_LINTS.name.to_string(),
	rustc_lint::builtin::UNKNOWN_LINTS.name.to_string(),
	rustc_lint::builtin::UNEXPECTED_CFGS.name.to_string(),
	// this lint is needed to support `#[expect]` attributes
	rustc_lint::builtin::UNFULFILLED_LINT_EXPECTATIONS.name.to_string(),
	];
	lints_to_show.extend(crate::lint::RUSTDOC_LINTS.iter().map(\|lint\| lint.name.to_string()));

	let (lint_opts, lint_caps) = crate::lint::init_lints(lints_to_show, lint_opts, \|lint\| {
	Some((lint.name_lower(), lint::Allow))
	});

	let crate_types =
	if proc_macro_crate { vec![CrateType::ProcMacro] } else { vec![CrateType::Rlib] };
	let resolve_doc_links =
	if *document_private { ResolveDocLinks::All } else { ResolveDocLinks::Exported };
	let test = scrape_examples_options.map(\|opts\| opts.scrape_tests).unwrap_or(false);
	// plays with error output here!
	let sessopts = config::Options {
	maybe_sysroot,
	search_paths: libs,
	crate_types,
	lint_opts,
	lint_cap,
	cg: codegen_options,
	externs,
	target_triple: target,
	unstable_features: UnstableFeatures::from_environment(crate_name.as_deref()),
	actually_rustdoc: true,
	resolve_doc_links,
	unstable_opts,
	error_format,
	diagnostic_width,
	edition,
	describe_lints,
	crate_name,
	test,
	..Options::default()
	};

	interface::Config {
	opts: sessopts,
	crate_cfg: cfgs,
	crate_check_cfg: check_cfgs,
	input,
	output_file: None,
	output_dir: None,
	file_loader: None,
	locale_resources: rustc_driver::DEFAULT_LOCALE_RESOURCES,
	lint_caps,
	psess_created: None,
	hash_untracked_state: None,
	register_lints: Some(Box::new(crate::lint::register_lints)),
	override_queries: Some(\|_sess, providers\| {
	// We do not register late module lints, so this only runs `MissingDoc`.
	// Most lints will require typechecking, so just don't run them.
	providers.lint_mod = \|tcx, module_def_id\| late_lint_mod(tcx, module_def_id, MissingDoc);
	// hack so that `used_trait_imports` won't try to call typeck
	providers.used_trait_imports = \|_, _\| {
	static EMPTY_SET: LazyLock<UnordSet<LocalDefId>> = LazyLock::new(UnordSet::default);
	&EMPTY_SET
	};
	// In case typeck does end up being called, don't ICE in case there were name resolution errors
	providers.typeck = move \|tcx, def_id\| {
	// Closures' tables come from their outermost function,
	// as they are part of the same "inference environment".
	// This avoids emitting errors for the parent twice (see similar code in `typeck_with_fallback`)
	let typeck_root_def_id = tcx.typeck_root_def_id(def_id.to_def_id()).expect_local();
	if typeck_root_def_id != def_id {
	return tcx.typeck(typeck_root_def_id);
	}

	let hir = tcx.hir();
	let body = hir.body(hir.body_owned_by(def_id));
	debug!("visiting body for {def_id:?}");
	EmitIgnoredResolutionErrors::new(tcx).visit_body(body);
	(rustc_interface::DEFAULT_QUERY_PROVIDERS.typeck)(tcx, def_id)
	};
	}),
	make_codegen_backend: None,
	registry: rustc_driver::diagnostics_registry(),
	ice_file: None,
	using_internal_features,
	expanded_args,
	}
	}

	pub(crate) fn run_global_ctxt(
	tcx: TyCtxt<'_>,
	show_coverage: bool,
	render_options: RenderOptions,
	output_format: OutputFormat,
	) -> Result<(clean::Crate, RenderOptions, Cache), ErrorGuaranteed> {
	// Certain queries assume that some checks were run elsewhere
	// (see https://github.com/rust-lang/rust/pull/73566#issuecomment-656954425),
	// so type-check everything other than function bodies in this crate before running lints.

	// NOTE: this does not call `tcx.analysis()` so that we won't
	// typeck function bodies or run the default rustc lints.
	// (see `override_queries` in the `config`)

	// NOTE: These are copy/pasted from typeck/lib.rs and should be kept in sync with those changes.
	let _ = tcx.sess.time("wf_checking", \|\| {
	tcx.hir().try_par_for_each_module(\|module\| tcx.ensure().check_mod_type_wf(module))
	});

	if let Some(guar) = tcx.dcx().has_errors() {
	return Err(guar);
	}

	tcx.sess.time("missing_docs", \|\| rustc_lint::check_crate(tcx));
	tcx.sess.time("check_mod_attrs", \|\| {
	tcx.hir().for_each_module(\|module\| tcx.ensure().check_mod_attrs(module))
	});
	rustc_passes::stability::check_unused_or_stable_features(tcx);

	let auto_traits =
	tcx.all_traits().filter(\|&trait_def_id\| tcx.trait_is_auto(trait_def_id)).collect();

	let mut ctxt = DocContext {
	tcx,
	param_env: ParamEnv::empty(),
	external_traits: Default::default(),
	active_extern_traits: Default::default(),
	args: Default::default(),
	current_type_aliases: Default::default(),
	impl_trait_bounds: Default::default(),
	generated_synthetics: Default::default(),
	auto_traits,
	cache: Cache::new(render_options.document_private, render_options.document_hidden),
	inlined: FxHashSet::default(),
	output_format,
	render_options,
	show_coverage,
	};

	for cnum in tcx.crates(()) {
	crate::visit_lib::lib_embargo_visit_item(&mut ctxt, cnum.as_def_id());
	}

	// Small hack to force the Sized trait to be present.
	//
	// Note that in case of `#![no_core]`, the trait is not available.
	if let Some(sized_trait_did) = ctxt.tcx.lang_items().sized_trait() {
	let sized_trait = build_external_trait(&mut ctxt, sized_trait_did);
	ctxt.external_traits.borrow_mut().insert(sized_trait_did, sized_trait);
	}

	debug!("crate: {:?}", tcx.hir().krate());

	let mut krate = tcx.sess.time("clean_crate", \|\| clean::krate(&mut ctxt));

	if krate.module.doc_value().is_empty() {
	let help = format!(
	"The following guide may be of use:\n\
	{}/rustdoc/how-to-write-documentation.html",
	crate::DOC_RUST_LANG_ORG_CHANNEL
	);
	tcx.node_lint(
	crate::lint::MISSING_CRATE_LEVEL_DOCS,
	DocContext::as_local_hir_id(tcx, krate.module.item_id).unwrap(),
	"no documentation found for this crate's top-level module",
	\|lint\| {
	lint.help(help);
	},
	);
	}

	fn report_deprecated_attr(name: &str, dcx: &rustc_errors::DiagCtxt, sp: Span) {
	let mut msg =
	dcx.struct_span_warn(sp, format!("the `#![doc({name})]` attribute is deprecated"));
	msg.note(
	"see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
	for more information",
	);

	if name == "no_default_passes" {
	msg.help("`#![doc(no_default_passes)]` no longer functions; you may want to use `#![doc(document_private_items)]`");
	} else if name.starts_with("passes") {
	msg.help("`#![doc(passes = \"...\")]` no longer functions; you may want to use `#![doc(document_private_items)]`");
	} else if name.starts_with("plugins") {
	msg.warn("`#![doc(plugins = \"...\")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>");
	}

	msg.emit();
	}

	// Process all of the crate attributes, extracting plugin metadata along
	// with the passes which we are supposed to run.
	for attr in krate.module.attrs.lists(sym::doc) {
	let dcx = ctxt.sess().dcx();

	let name = attr.name_or_empty();
	// `plugins = "..."`, `no_default_passes`, and `passes = "..."` have no effect
	if attr.is_word() && name == sym::no_default_passes {
	report_deprecated_attr("no_default_passes", dcx, attr.span());
	} else if attr.value_str().is_some() {
	match name {
	sym::passes => {
	report_deprecated_attr("passes = \"...\"", dcx, attr.span());
	}
	sym::plugins => {
	report_deprecated_attr("plugins = \"...\"", dcx, attr.span());
	}
	_ => (),
	}
	}

	if attr.is_word() && name == sym::document_private_items {
	ctxt.render_options.document_private = true;
	}
	}

	info!("Executing passes");

	for p in passes::defaults(show_coverage) {
	let run = match p.condition {
	Always => true,
	WhenDocumentPrivate => ctxt.render_options.document_private,
	WhenNotDocumentPrivate => !ctxt.render_options.document_private,
	WhenNotDocumentHidden => !ctxt.render_options.document_hidden,
	};
	if run {
	debug!("running pass {}", p.pass.name);
	krate = tcx.sess.time(p.pass.name, \|\| (p.pass.run)(krate, &mut ctxt));
	}
	}

	tcx.sess.time("check_lint_expectations", \|\| tcx.check_expectations(Some(sym::rustdoc)));

	if let Some(guar) = tcx.dcx().has_errors() {
	return Err(guar);
	}

	krate = tcx.sess.time("create_format_cache", \|\| Cache::populate(&mut ctxt, krate));

	Ok((krate, ctxt.render_options, ctxt.cache))
	}

	/// Due to <https://github.com/rust-lang/rust/pull/73566>,
	/// the name resolution pass may find errors that are never emitted.
	/// If typeck is called after this happens, then we'll get an ICE:
	/// 'Res::Error found but not reported'. To avoid this, emit the errors now.
	struct EmitIgnoredResolutionErrors<'tcx> {
	tcx: TyCtxt<'tcx>,
	}

	impl<'tcx> EmitIgnoredResolutionErrors<'tcx> {
	fn new(tcx: TyCtxt<'tcx>) -> Self {
	Self { tcx }
	}
	}

	impl<'tcx> Visitor<'tcx> for EmitIgnoredResolutionErrors<'tcx> {
	type NestedFilter = nested_filter::OnlyBodies;

	fn nested_visit_map(&mut self) -> Self::Map {
	// We need to recurse into nested closures,
	// since those will fallback to the parent for type checking.
	self.tcx.hir()
	}

	fn visit_path(&mut self, path: &Path<'tcx>, _id: HirId) {
	debug!("visiting path {path:?}");
	if path.res == Res::Err {
	// We have less context here than in rustc_resolve,
	// so we can only emit the name and span.
	// However we can give a hint that rustc_resolve will have more info.
	let label = format!(
	"could not resolve path `{}`",
	path.segments
	.iter()
	.map(\|segment\| segment.ident.as_str())
	.intersperse("::")
	.collect::<String>()
	);
	rustc_errors::struct_span_code_err!(
	self.tcx.dcx(),
	path.span,
	E0433,
	"failed to resolve: {label}",
	)
	.with_span_label(path.span, label)
	.with_note("this error was originally ignored because you are running `rustdoc`")
	.with_note("try running again with `rustc` or `cargo check` and you may get a more detailed error")
	.emit();
	}
	// We could have an outer resolution that succeeded,
	// but with generic parameters that failed.
	// Recurse into the segments so we catch those too.
	intravisit::walk_path(self, path);
	}
	}

	/// `DefId` or parameter index (`ty::ParamTy.index`) of a synthetic type parameter
	/// for `impl Trait` in argument position.
	#[derive(Clone, Copy, PartialEq, Eq, Hash)]
	pub(crate) enum ImplTraitParam {
	DefId(DefId),
	ParamIndex(u32),
	}

	impl From<DefId> for ImplTraitParam {
	fn from(did: DefId) -> Self {
	ImplTraitParam::DefId(did)
	}
	}

	impl From<u32> for ImplTraitParam {
	fn from(idx: u32) -> Self {
	ImplTraitParam::ParamIndex(idx)
	}
	}