From c836f95e966b361b930a738f7bea75fbc5b8d9c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Sun, 14 Sep 2025 02:13:11 +0200 Subject: [PATCH 1/2] rustdoc: Nuke `--passes=list` --- src/librustdoc/config.rs | 33 ------- .../passes/calculate_doc_coverage.rs | 12 +-- src/librustdoc/passes/check_doc_cfg.rs | 8 +- .../passes/check_doc_test_visibility.rs | 7 +- .../passes/collect_intra_doc_links.rs | 6 +- src/librustdoc/passes/collect_trait_impls.rs | 14 ++- src/librustdoc/passes/lint.rs | 6 +- src/librustdoc/passes/mod.rs | 90 ++++++------------- src/librustdoc/passes/propagate_doc_cfg.rs | 11 ++- src/librustdoc/passes/propagate_stability.rs | 7 +- .../passes/strip_aliased_non_local.rs | 9 +- src/librustdoc/passes/strip_hidden.rs | 9 +- src/librustdoc/passes/strip_priv_imports.rs | 10 +-- src/librustdoc/passes/strip_private.rs | 14 +-- tests/rustdoc-ui/issues/issue-91713.stdout | 31 ------- 15 files changed, 67 insertions(+), 200 deletions(-) delete mode 100644 tests/rustdoc-ui/issues/issue-91713.stdout diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 5d16dff24c69a..0a5725b269f1e 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -24,7 +24,6 @@ use crate::externalfiles::ExternalHtml; use crate::html::markdown::IdMap; use crate::html::render::StylePath; use crate::html::static_files; -use crate::passes::{self, Condition}; use crate::scrape_examples::{AllCallLocations, ScrapeExamplesOptions}; use crate::{html, opts, theme}; @@ -421,38 +420,6 @@ impl Options { // check for deprecated options check_deprecated_options(matches, dcx); - if matches.opt_strs("passes") == ["list"] { - println!("Available passes for running rustdoc:"); - for pass in passes::PASSES { - println!("{:>20} - {}", pass.name, pass.description); - } - println!("\nDefault passes for rustdoc:"); - for p in passes::DEFAULT_PASSES { - print!("{:>20}", p.pass.name); - println_condition(p.condition); - } - - if nightly_options::match_is_nightly_build(matches) { - println!("\nPasses run with `--show-coverage`:"); - for p in passes::COVERAGE_PASSES { - print!("{:>20}", p.pass.name); - println_condition(p.condition); - } - } - - fn println_condition(condition: Condition) { - use Condition::*; - match condition { - Always => println!(), - WhenDocumentPrivate => println!(" (when --document-private-items)"), - WhenNotDocumentPrivate => println!(" (when not --document-private-items)"), - WhenNotDocumentHidden => println!(" (when not --document-hidden-items)"), - } - } - - return None; - } - let mut emit = FxIndexMap::<_, EmitType>::default(); for list in matches.opt_strs("emit") { for kind in list.split(',') { diff --git a/src/librustdoc/passes/calculate_doc_coverage.rs b/src/librustdoc/passes/calculate_doc_coverage.rs index 66d8b667a4cad..a5b1212fbb09c 100644 --- a/src/librustdoc/passes/calculate_doc_coverage.rs +++ b/src/librustdoc/passes/calculate_doc_coverage.rs @@ -1,4 +1,7 @@ -//! Calculates information used for the --show-coverage flag. +//! Calculates information used for the `--show-coverage` flag. +//! +//! More specifically, it counts the number of items with documentation, ones with +//! "examples" (i.e., non-ignored Rust code blocks) and various totals. use std::collections::BTreeMap; use std::ops; @@ -18,11 +21,8 @@ use crate::passes::Pass; use crate::passes::check_doc_test_visibility::{Tests, should_have_doc_example}; use crate::visit::DocVisitor; -pub(crate) const CALCULATE_DOC_COVERAGE: Pass = Pass { - name: "calculate-doc-coverage", - run: Some(calculate_doc_coverage), - description: "counts the number of items with and without documentation", -}; +pub(crate) const CALCULATE_DOC_COVERAGE: Pass = + Pass { name: "calculate-doc-coverage", run: Some(calculate_doc_coverage) }; fn calculate_doc_coverage(krate: clean::Crate, ctx: &mut DocContext<'_>) -> clean::Crate { let mut calc = CoverageCalculator { items: Default::default(), ctx }; diff --git a/src/librustdoc/passes/check_doc_cfg.rs b/src/librustdoc/passes/check_doc_cfg.rs index 3284da77a0222..877fa7e311735 100644 --- a/src/librustdoc/passes/check_doc_cfg.rs +++ b/src/librustdoc/passes/check_doc_cfg.rs @@ -1,3 +1,5 @@ +//! Checks `#[doc(cfg(…))]` for unexpected cfgs wrt. `--check-cfg`. + use rustc_hir::HirId; use rustc_hir::def_id::LocalDefId; use rustc_middle::ty::TyCtxt; @@ -8,11 +10,7 @@ use crate::clean::{Attributes, Crate, Item}; use crate::core::DocContext; use crate::visit::DocVisitor; -pub(crate) const CHECK_DOC_CFG: Pass = Pass { - name: "check-doc-cfg", - run: Some(check_doc_cfg), - description: "checks `#[doc(cfg(...))]` for stability feature and unexpected cfgs", -}; +pub(crate) const CHECK_DOC_CFG: Pass = Pass { name: "check-doc-cfg", run: Some(check_doc_cfg) }; pub(crate) fn check_doc_cfg(krate: Crate, cx: &mut DocContext<'_>) -> Crate { let mut checker = DocCfgChecker { cx }; diff --git a/src/librustdoc/passes/check_doc_test_visibility.rs b/src/librustdoc/passes/check_doc_test_visibility.rs index 39116061f4854..da0bfe69ef1b9 100644 --- a/src/librustdoc/passes/check_doc_test_visibility.rs +++ b/src/librustdoc/passes/check_doc_test_visibility.rs @@ -18,11 +18,8 @@ use crate::core::DocContext; use crate::html::markdown::{ErrorCodes, Ignore, LangString, MdRelLine, find_testable_code}; use crate::visit::DocVisitor; -pub(crate) const CHECK_DOC_TEST_VISIBILITY: Pass = Pass { - name: "check_doc_test_visibility", - run: Some(check_doc_test_visibility), - description: "run various visibility-related lints on doctests", -}; +pub(crate) const CHECK_DOC_TEST_VISIBILITY: Pass = + Pass { name: "check_doc_test_visibility", run: Some(check_doc_test_visibility) }; struct DocTestVisibilityLinter<'a, 'tcx> { cx: &'a mut DocContext<'tcx>, diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs index 4e4f21bf926fe..cf4888a17773b 100644 --- a/src/librustdoc/passes/collect_intra_doc_links.rs +++ b/src/librustdoc/passes/collect_intra_doc_links.rs @@ -1,6 +1,6 @@ -//! This module implements [RFC 1946]: Intra-rustdoc-links +//! Resolves intra-doc links ([RFC 1946]). //! -//! [RFC 1946]: https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md +//! [RFC 1946]: https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html use std::borrow::Cow; use std::fmt::Display; @@ -38,7 +38,7 @@ use crate::passes::Pass; use crate::visit::DocVisitor; pub(crate) const COLLECT_INTRA_DOC_LINKS: Pass = - Pass { name: "collect-intra-doc-links", run: None, description: "resolves intra-doc links" }; + Pass { name: "collect-intra-doc-links", run: None }; pub(crate) fn collect_intra_doc_links<'a, 'tcx>( krate: Crate, diff --git a/src/librustdoc/passes/collect_trait_impls.rs b/src/librustdoc/passes/collect_trait_impls.rs index 2339a6b69cd8a..c9fd4323e4421 100644 --- a/src/librustdoc/passes/collect_trait_impls.rs +++ b/src/librustdoc/passes/collect_trait_impls.rs @@ -1,6 +1,7 @@ -//! Collects trait impls for each item in the crate. For example, if a crate -//! defines a struct that implements a trait, this pass will note that the -//! struct implements that trait. +//! Collects trait impls for each item in the crate. +//! +//! For example, if a crate defines a struct that implements a trait, +//! this pass will note that the struct implements that trait. use rustc_data_structures::fx::FxHashSet; use rustc_hir::def_id::{DefId, DefIdMap, DefIdSet, LOCAL_CRATE}; @@ -14,11 +15,8 @@ use crate::core::DocContext; use crate::formats::cache::Cache; use crate::visit::DocVisitor; -pub(crate) const COLLECT_TRAIT_IMPLS: Pass = Pass { - name: "collect-trait-impls", - run: Some(collect_trait_impls), - description: "retrieves trait impls for items in the crate", -}; +pub(crate) const COLLECT_TRAIT_IMPLS: Pass = + Pass { name: "collect-trait-impls", run: Some(collect_trait_impls) }; pub(crate) fn collect_trait_impls(mut krate: Crate, cx: &mut DocContext<'_>) -> Crate { let tcx = cx.tcx; diff --git a/src/librustdoc/passes/lint.rs b/src/librustdoc/passes/lint.rs index 7740d14148bf0..1086707588921 100644 --- a/src/librustdoc/passes/lint.rs +++ b/src/librustdoc/passes/lint.rs @@ -1,5 +1,4 @@ -//! Runs several rustdoc lints, consolidating them into a single pass for -//! efficiency and simplicity. +//! Runs several rustdoc lints, consolidating them into a single pass for efficiency and simplicity. mod bare_urls; mod check_code_block_syntax; @@ -12,8 +11,7 @@ use crate::clean::*; use crate::core::DocContext; use crate::visit::DocVisitor; -pub(crate) const RUN_LINTS: Pass = - Pass { name: "run-lints", run: Some(run_lints), description: "runs some of rustdoc's lints" }; +pub(crate) const RUN_LINTS: Pass = Pass { name: "run-lints", run: Some(run_lints) }; struct Linter<'a, 'tcx> { cx: &'a mut DocContext<'tcx>, diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs index a1e8e75306235..7dd7885b48502 100644 --- a/src/librustdoc/passes/mod.rs +++ b/src/librustdoc/passes/mod.rs @@ -8,41 +8,18 @@ use crate::core::DocContext; mod stripper; pub(crate) use stripper::*; -mod strip_aliased_non_local; -pub(crate) use self::strip_aliased_non_local::STRIP_ALIASED_NON_LOCAL; - -mod strip_hidden; -pub(crate) use self::strip_hidden::STRIP_HIDDEN; - -mod strip_private; -pub(crate) use self::strip_private::STRIP_PRIVATE; - -mod strip_priv_imports; -pub(crate) use self::strip_priv_imports::STRIP_PRIV_IMPORTS; - -mod propagate_doc_cfg; -pub(crate) use self::propagate_doc_cfg::PROPAGATE_DOC_CFG; - -mod propagate_stability; -pub(crate) use self::propagate_stability::PROPAGATE_STABILITY; - -pub(crate) mod collect_intra_doc_links; -pub(crate) use self::collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS; - -mod check_doc_test_visibility; -pub(crate) use self::check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY; - +mod calculate_doc_coverage; mod check_doc_cfg; -pub(crate) use self::check_doc_cfg::CHECK_DOC_CFG; - +mod check_doc_test_visibility; +pub(crate) mod collect_intra_doc_links; mod collect_trait_impls; -pub(crate) use self::collect_trait_impls::COLLECT_TRAIT_IMPLS; - -mod calculate_doc_coverage; -pub(crate) use self::calculate_doc_coverage::CALCULATE_DOC_COVERAGE; - mod lint; -pub(crate) use self::lint::RUN_LINTS; +mod propagate_doc_cfg; +mod propagate_stability; +mod strip_aliased_non_local; +mod strip_hidden; +mod strip_priv_imports; +mod strip_private; /// A single pass over the cleaned documentation. /// @@ -51,7 +28,6 @@ pub(crate) use self::lint::RUN_LINTS; pub(crate) struct Pass { pub(crate) name: &'static str, pub(crate) run: Option) -> clean::Crate>, - pub(crate) description: &'static str, } /// In a list of passes, a pass that may or may not need to be run depending on options. @@ -73,42 +49,26 @@ pub(crate) enum Condition { WhenNotDocumentHidden, } -/// The full list of passes. -pub(crate) const PASSES: &[Pass] = &[ - CHECK_DOC_CFG, - CHECK_DOC_TEST_VISIBILITY, - PROPAGATE_DOC_CFG, - STRIP_ALIASED_NON_LOCAL, - STRIP_HIDDEN, - STRIP_PRIVATE, - STRIP_PRIV_IMPORTS, - PROPAGATE_STABILITY, - COLLECT_INTRA_DOC_LINKS, - COLLECT_TRAIT_IMPLS, - CALCULATE_DOC_COVERAGE, - RUN_LINTS, -]; - /// The list of passes run by default. -pub(crate) const DEFAULT_PASSES: &[ConditionalPass] = &[ - ConditionalPass::always(COLLECT_TRAIT_IMPLS), - ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY), - ConditionalPass::always(CHECK_DOC_CFG), - ConditionalPass::always(STRIP_ALIASED_NON_LOCAL), - ConditionalPass::always(PROPAGATE_DOC_CFG), - ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden), - ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate), - ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate), - ConditionalPass::always(COLLECT_INTRA_DOC_LINKS), - ConditionalPass::always(PROPAGATE_STABILITY), - ConditionalPass::always(RUN_LINTS), +const DEFAULT_PASSES: &[ConditionalPass] = &[ + ConditionalPass::always(collect_trait_impls::COLLECT_TRAIT_IMPLS), + ConditionalPass::always(check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY), + ConditionalPass::always(check_doc_cfg::CHECK_DOC_CFG), + ConditionalPass::always(strip_aliased_non_local::STRIP_ALIASED_NON_LOCAL), + ConditionalPass::always(propagate_doc_cfg::PROPAGATE_DOC_CFG), + ConditionalPass::new(strip_hidden::STRIP_HIDDEN, WhenNotDocumentHidden), + ConditionalPass::new(strip_private::STRIP_PRIVATE, WhenNotDocumentPrivate), + ConditionalPass::new(strip_priv_imports::STRIP_PRIV_IMPORTS, WhenDocumentPrivate), + ConditionalPass::always(collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS), + ConditionalPass::always(propagate_stability::PROPAGATE_STABILITY), + ConditionalPass::always(lint::RUN_LINTS), ]; /// The list of default passes run when `--doc-coverage` is passed to rustdoc. -pub(crate) const COVERAGE_PASSES: &[ConditionalPass] = &[ - ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden), - ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate), - ConditionalPass::always(CALCULATE_DOC_COVERAGE), +const COVERAGE_PASSES: &[ConditionalPass] = &[ + ConditionalPass::new(strip_hidden::STRIP_HIDDEN, WhenNotDocumentHidden), + ConditionalPass::new(strip_private::STRIP_PRIVATE, WhenNotDocumentPrivate), + ConditionalPass::always(calculate_doc_coverage::CALCULATE_DOC_COVERAGE), ]; impl ConditionalPass { diff --git a/src/librustdoc/passes/propagate_doc_cfg.rs b/src/librustdoc/passes/propagate_doc_cfg.rs index c0b48ab51c7eb..2d12a3979304c 100644 --- a/src/librustdoc/passes/propagate_doc_cfg.rs +++ b/src/librustdoc/passes/propagate_doc_cfg.rs @@ -1,4 +1,6 @@ -//! Propagates [`#[doc(cfg(...))]`](https://github.com/rust-lang/rust/issues/43781) to child items. +//! Propagates `#[doc(cfg(…))]` ([RFC 3631]) to child items. +//! +//! [RFC 3631]: https://rust-lang.github.io/rfcs/3631-rustdoc-cfgs-handling.html use rustc_ast::token::{Token, TokenKind}; use rustc_ast::tokenstream::{TokenStream, TokenTree}; @@ -11,11 +13,8 @@ use crate::core::DocContext; use crate::fold::DocFolder; use crate::passes::Pass; -pub(crate) const PROPAGATE_DOC_CFG: Pass = Pass { - name: "propagate-doc-cfg", - run: Some(propagate_doc_cfg), - description: "propagates `#[doc(cfg(...))]` to child items", -}; +pub(crate) const PROPAGATE_DOC_CFG: Pass = + Pass { name: "propagate-doc-cfg", run: Some(propagate_doc_cfg) }; pub(crate) fn propagate_doc_cfg(cr: Crate, cx: &mut DocContext<'_>) -> Crate { if cx.tcx.features().doc_cfg() { diff --git a/src/librustdoc/passes/propagate_stability.rs b/src/librustdoc/passes/propagate_stability.rs index 5139ca301dd3d..67c59f794454f 100644 --- a/src/librustdoc/passes/propagate_stability.rs +++ b/src/librustdoc/passes/propagate_stability.rs @@ -14,11 +14,8 @@ use crate::core::DocContext; use crate::fold::DocFolder; use crate::passes::Pass; -pub(crate) const PROPAGATE_STABILITY: Pass = Pass { - name: "propagate-stability", - run: Some(propagate_stability), - description: "propagates stability to child items", -}; +pub(crate) const PROPAGATE_STABILITY: Pass = + Pass { name: "propagate-stability", run: Some(propagate_stability) }; pub(crate) fn propagate_stability(cr: Crate, cx: &mut DocContext<'_>) -> Crate { let crate_stability = cx.tcx.lookup_stability(CRATE_DEF_ID); diff --git a/src/librustdoc/passes/strip_aliased_non_local.rs b/src/librustdoc/passes/strip_aliased_non_local.rs index bb13308e6c2a9..0e16b56891887 100644 --- a/src/librustdoc/passes/strip_aliased_non_local.rs +++ b/src/librustdoc/passes/strip_aliased_non_local.rs @@ -1,3 +1,5 @@ +//! Strips all non-local private aliases items from the output. + use rustc_middle::ty::{TyCtxt, Visibility}; use crate::clean; @@ -6,11 +8,8 @@ use crate::core::DocContext; use crate::fold::{DocFolder, strip_item}; use crate::passes::Pass; -pub(crate) const STRIP_ALIASED_NON_LOCAL: Pass = Pass { - name: "strip-aliased-non-local", - run: Some(strip_aliased_non_local), - description: "strips all non-local private aliased items from the output", -}; +pub(crate) const STRIP_ALIASED_NON_LOCAL: Pass = + Pass { name: "strip-aliased-non-local", run: Some(strip_aliased_non_local) }; fn strip_aliased_non_local(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { let mut stripper = AliasedNonLocalStripper { tcx: cx.tcx }; diff --git a/src/librustdoc/passes/strip_hidden.rs b/src/librustdoc/passes/strip_hidden.rs index 27065d7675bb7..53611e87ef091 100644 --- a/src/librustdoc/passes/strip_hidden.rs +++ b/src/librustdoc/passes/strip_hidden.rs @@ -1,4 +1,4 @@ -//! Strip all doc(hidden) items from the output. +//! Strip all `#[doc(hidden)]` items from the output. use std::mem; @@ -14,13 +14,8 @@ use crate::core::DocContext; use crate::fold::{DocFolder, strip_item}; use crate::passes::{ImplStripper, Pass}; -pub(crate) const STRIP_HIDDEN: Pass = Pass { - name: "strip-hidden", - run: Some(strip_hidden), - description: "strips all `#[doc(hidden)]` items from the output", -}; +pub(crate) const STRIP_HIDDEN: Pass = Pass { name: "strip-hidden", run: Some(strip_hidden) }; -/// Strip items marked `#[doc(hidden)]` pub(crate) fn strip_hidden(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { let mut retained = ItemIdSet::default(); let is_json_output = cx.is_json_output(); diff --git a/src/librustdoc/passes/strip_priv_imports.rs b/src/librustdoc/passes/strip_priv_imports.rs index a169797e00b2a..a0733dde7073d 100644 --- a/src/librustdoc/passes/strip_priv_imports.rs +++ b/src/librustdoc/passes/strip_priv_imports.rs @@ -1,16 +1,12 @@ -//! Strips all private import statements (use, extern crate) from a -//! crate. +//! Strips all private imports (`use`, `extern crate`) from a crate. use crate::clean; use crate::core::DocContext; use crate::fold::DocFolder; use crate::passes::{ImportStripper, Pass}; -pub(crate) const STRIP_PRIV_IMPORTS: Pass = Pass { - name: "strip-priv-imports", - run: Some(strip_priv_imports), - description: "strips all private import statements (`use`, `extern crate`) from a crate", -}; +pub(crate) const STRIP_PRIV_IMPORTS: Pass = + Pass { name: "strip-priv-imports", run: Some(strip_priv_imports) }; pub(crate) fn strip_priv_imports(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { let is_json_output = cx.is_json_output(); diff --git a/src/librustdoc/passes/strip_private.rs b/src/librustdoc/passes/strip_private.rs index 045bf0c0be029..2858eabecf3d2 100644 --- a/src/librustdoc/passes/strip_private.rs +++ b/src/librustdoc/passes/strip_private.rs @@ -1,20 +1,14 @@ -//! Strip all private items from the output. Additionally implies strip_priv_imports. -//! Basically, the goal is to remove items that are not relevant for public documentation. +//! Strip all private items from the output. +//! +//! Implies `strip_priv_imports`. use crate::clean::{self, ItemIdSet}; use crate::core::DocContext; use crate::fold::DocFolder; use crate::passes::{ImplStripper, ImportStripper, Pass, Stripper}; -pub(crate) const STRIP_PRIVATE: Pass = Pass { - name: "strip-private", - run: Some(strip_private), - description: "strips all private items from a crate which cannot be seen externally, \ - implies strip-priv-imports", -}; +pub(crate) const STRIP_PRIVATE: Pass = Pass { name: "strip-private", run: Some(strip_private) }; -/// Strip private items from the point of view of a crate or externally from a -/// crate, specified by the `xcrate` flag. pub(crate) fn strip_private(mut krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { // This stripper collects all *retained* nodes. let mut retained = ItemIdSet::default(); diff --git a/tests/rustdoc-ui/issues/issue-91713.stdout b/tests/rustdoc-ui/issues/issue-91713.stdout deleted file mode 100644 index c0cd454e8f3ad..0000000000000 --- a/tests/rustdoc-ui/issues/issue-91713.stdout +++ /dev/null @@ -1,31 +0,0 @@ -Available passes for running rustdoc: - check-doc-cfg - checks `#[doc(cfg(...))]` for stability feature and unexpected cfgs -check_doc_test_visibility - run various visibility-related lints on doctests - propagate-doc-cfg - propagates `#[doc(cfg(...))]` to child items -strip-aliased-non-local - strips all non-local private aliased items from the output - strip-hidden - strips all `#[doc(hidden)]` items from the output - strip-private - strips all private items from a crate which cannot be seen externally, implies strip-priv-imports - strip-priv-imports - strips all private import statements (`use`, `extern crate`) from a crate - propagate-stability - propagates stability to child items -collect-intra-doc-links - resolves intra-doc links - collect-trait-impls - retrieves trait impls for items in the crate -calculate-doc-coverage - counts the number of items with and without documentation - run-lints - runs some of rustdoc's lints - -Default passes for rustdoc: - collect-trait-impls -check_doc_test_visibility - check-doc-cfg -strip-aliased-non-local - propagate-doc-cfg - strip-hidden (when not --document-hidden-items) - strip-private (when not --document-private-items) - strip-priv-imports (when --document-private-items) -collect-intra-doc-links - propagate-stability - run-lints - -Passes run with `--show-coverage`: - strip-hidden (when not --document-hidden-items) - strip-private (when not --document-private-items) -calculate-doc-coverage From 7a0a82cc1511f8feefdefaac1a3508ace66aa305 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Sat, 27 Sep 2025 15:46:38 +0200 Subject: [PATCH 2/2] rustdoc: Defossilize the passes infrastructure --- src/librustdoc/core.rs | 53 +++++---- .../passes/calculate_doc_coverage.rs | 9 +- src/librustdoc/passes/check_doc_cfg.rs | 3 - .../passes/check_doc_test_visibility.rs | 7 +- .../passes/collect_intra_doc_links.rs | 4 - src/librustdoc/passes/collect_trait_impls.rs | 4 - src/librustdoc/passes/lint.rs | 5 +- src/librustdoc/passes/mod.rs | 103 ++++-------------- src/librustdoc/passes/propagate_doc_cfg.rs | 4 - src/librustdoc/passes/propagate_stability.rs | 4 - .../passes/strip_aliased_non_local.rs | 9 +- src/librustdoc/passes/strip_hidden.rs | 8 +- src/librustdoc/passes/strip_priv_imports.rs | 10 +- src/librustdoc/passes/strip_private.rs | 8 +- 14 files changed, 75 insertions(+), 156 deletions(-) diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 6e70f5b41c426..2a51f1240f602 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -34,7 +34,6 @@ use crate::config::{Options as RustdocOptions, OutputFormat, RenderOptions}; use crate::formats::cache::Cache; use crate::html::macro_expansion::{ExpandedCode, source_macro_expansion}; use crate::passes; -use crate::passes::Condition::*; use crate::passes::collect_intra_doc_links::LinkCollector; pub(crate) struct DocContext<'tcx> { @@ -423,30 +422,31 @@ pub(crate) fn run_global_ctxt( ); } - info!("Executing passes"); - - let mut visited = FxHashMap::default(); - let mut ambiguous = FxIndexMap::default(); - - for p in passes::defaults(show_coverage) { - let run = match p.condition { - Always => true, - WhenDocumentPrivate => ctxt.document_private(), - WhenNotDocumentPrivate => !ctxt.document_private(), - WhenNotDocumentHidden => !ctxt.document_hidden(), - }; - if run { - debug!("running pass {}", p.pass.name); - if let Some(run_fn) = p.pass.run { - krate = tcx.sess.time(p.pass.name, || run_fn(krate, &mut ctxt)); - } else { - let (k, LinkCollector { visited_links, ambiguous_links, .. }) = - passes::collect_intra_doc_links::collect_intra_doc_links(krate, &mut ctxt); - krate = k; - visited = visited_links; - ambiguous = ambiguous_links; - } - } + info!("running passes"); + passes::initialize!(tcx, ctxt); + + let mut visited_links = FxHashMap::default(); + let mut ambiguous_links = FxIndexMap::default(); + + if !show_coverage { + krate = track!(collect_trait_impls(krate)); + krate = track!(check_doc_test_visibility(krate)); + krate = track!(check_doc_cfg(krate)); + krate = track!(strip_aliased_non_local(krate)); + krate = track!(propagate_doc_cfg(krate)); + } + + krate = track!(strip_hidden(krate)); + krate = track!(strip_private(krate)); + + if show_coverage { + krate = track!(calculate_doc_coverage(krate)); + } else { + krate = track!(strip_priv_imports(krate)); + (krate, LinkCollector { visited_links, ambiguous_links, .. }) = + track!(collect_intra_doc_links(krate)); + krate = track!(propagate_stability(krate)); + krate = track!(lint(krate)); } tcx.sess.time("check_lint_expectations", || tcx.check_expectations(Some(sym::rustdoc))); @@ -454,8 +454,7 @@ pub(crate) fn run_global_ctxt( krate = tcx.sess.time("create_format_cache", || Cache::populate(&mut ctxt, krate, &render_options)); - let mut collector = - LinkCollector { cx: &mut ctxt, visited_links: visited, ambiguous_links: ambiguous }; + let mut collector = LinkCollector { cx: &mut ctxt, visited_links, ambiguous_links }; collector.resolve_ambiguities(); tcx.dcx().abort_if_errors(); diff --git a/src/librustdoc/passes/calculate_doc_coverage.rs b/src/librustdoc/passes/calculate_doc_coverage.rs index a5b1212fbb09c..a13ee453ac23a 100644 --- a/src/librustdoc/passes/calculate_doc_coverage.rs +++ b/src/librustdoc/passes/calculate_doc_coverage.rs @@ -17,14 +17,13 @@ use tracing::debug; use crate::clean; use crate::core::DocContext; use crate::html::markdown::{ErrorCodes, find_testable_code}; -use crate::passes::Pass; use crate::passes::check_doc_test_visibility::{Tests, should_have_doc_example}; use crate::visit::DocVisitor; -pub(crate) const CALCULATE_DOC_COVERAGE: Pass = - Pass { name: "calculate-doc-coverage", run: Some(calculate_doc_coverage) }; - -fn calculate_doc_coverage(krate: clean::Crate, ctx: &mut DocContext<'_>) -> clean::Crate { +pub(crate) fn calculate_doc_coverage( + krate: clean::Crate, + ctx: &mut DocContext<'_>, +) -> clean::Crate { let mut calc = CoverageCalculator { items: Default::default(), ctx }; calc.visit_crate(&krate); diff --git a/src/librustdoc/passes/check_doc_cfg.rs b/src/librustdoc/passes/check_doc_cfg.rs index 877fa7e311735..93d6a7313294f 100644 --- a/src/librustdoc/passes/check_doc_cfg.rs +++ b/src/librustdoc/passes/check_doc_cfg.rs @@ -5,13 +5,10 @@ use rustc_hir::def_id::LocalDefId; use rustc_middle::ty::TyCtxt; use rustc_span::sym; -use super::Pass; use crate::clean::{Attributes, Crate, Item}; use crate::core::DocContext; use crate::visit::DocVisitor; -pub(crate) const CHECK_DOC_CFG: Pass = Pass { name: "check-doc-cfg", run: Some(check_doc_cfg) }; - pub(crate) fn check_doc_cfg(krate: Crate, cx: &mut DocContext<'_>) -> Crate { let mut checker = DocCfgChecker { cx }; checker.visit_crate(&krate); diff --git a/src/librustdoc/passes/check_doc_test_visibility.rs b/src/librustdoc/passes/check_doc_test_visibility.rs index da0bfe69ef1b9..d9303ad1df5e9 100644 --- a/src/librustdoc/passes/check_doc_test_visibility.rs +++ b/src/librustdoc/passes/check_doc_test_visibility.rs @@ -10,17 +10,12 @@ use rustc_middle::lint::{LevelAndSource, LintLevelSource}; use rustc_session::lint; use tracing::debug; -use super::Pass; -use crate::clean; use crate::clean::utils::inherits_doc_hidden; -use crate::clean::*; +use crate::clean::{self, *}; use crate::core::DocContext; use crate::html::markdown::{ErrorCodes, Ignore, LangString, MdRelLine, find_testable_code}; use crate::visit::DocVisitor; -pub(crate) const CHECK_DOC_TEST_VISIBILITY: Pass = - Pass { name: "check_doc_test_visibility", run: Some(check_doc_test_visibility) }; - struct DocTestVisibilityLinter<'a, 'tcx> { cx: &'a mut DocContext<'tcx>, } diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs index cf4888a17773b..ead2b1eb1d7c7 100644 --- a/src/librustdoc/passes/collect_intra_doc_links.rs +++ b/src/librustdoc/passes/collect_intra_doc_links.rs @@ -34,12 +34,8 @@ use crate::clean::{self, Crate, Item, ItemId, ItemLink, PrimitiveType}; use crate::core::DocContext; use crate::html::markdown::{MarkdownLink, MarkdownLinkRange, markdown_links}; use crate::lint::{BROKEN_INTRA_DOC_LINKS, PRIVATE_INTRA_DOC_LINKS}; -use crate::passes::Pass; use crate::visit::DocVisitor; -pub(crate) const COLLECT_INTRA_DOC_LINKS: Pass = - Pass { name: "collect-intra-doc-links", run: None }; - pub(crate) fn collect_intra_doc_links<'a, 'tcx>( krate: Crate, cx: &'a mut DocContext<'tcx>, diff --git a/src/librustdoc/passes/collect_trait_impls.rs b/src/librustdoc/passes/collect_trait_impls.rs index c9fd4323e4421..f22776cb52566 100644 --- a/src/librustdoc/passes/collect_trait_impls.rs +++ b/src/librustdoc/passes/collect_trait_impls.rs @@ -9,15 +9,11 @@ use rustc_middle::ty; use rustc_span::symbol::sym; use tracing::debug; -use super::Pass; use crate::clean::*; use crate::core::DocContext; use crate::formats::cache::Cache; use crate::visit::DocVisitor; -pub(crate) const COLLECT_TRAIT_IMPLS: Pass = - Pass { name: "collect-trait-impls", run: Some(collect_trait_impls) }; - pub(crate) fn collect_trait_impls(mut krate: Crate, cx: &mut DocContext<'_>) -> Crate { let tcx = cx.tcx; // We need to check if there are errors before running this pass because it would crash when diff --git a/src/librustdoc/passes/lint.rs b/src/librustdoc/passes/lint.rs index 1086707588921..e9140c886fd7c 100644 --- a/src/librustdoc/passes/lint.rs +++ b/src/librustdoc/passes/lint.rs @@ -6,18 +6,15 @@ mod html_tags; mod redundant_explicit_links; mod unescaped_backticks; -use super::Pass; use crate::clean::*; use crate::core::DocContext; use crate::visit::DocVisitor; -pub(crate) const RUN_LINTS: Pass = Pass { name: "run-lints", run: Some(run_lints) }; - struct Linter<'a, 'tcx> { cx: &'a mut DocContext<'tcx>, } -pub(crate) fn run_lints(krate: Crate, cx: &mut DocContext<'_>) -> Crate { +pub(crate) fn lint(krate: Crate, cx: &mut DocContext<'_>) -> Crate { Linter { cx }.visit_crate(&krate); krate } diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs index 7dd7885b48502..3a8c84ab1c3e0 100644 --- a/src/librustdoc/passes/mod.rs +++ b/src/librustdoc/passes/mod.rs @@ -1,87 +1,30 @@ -//! Contains information about "passes", used to modify crate information during the documentation -//! process. - -use self::Condition::*; -use crate::clean; -use crate::core::DocContext; +//! The definitions of *passes* which transform crate information. mod stripper; pub(crate) use stripper::*; -mod calculate_doc_coverage; -mod check_doc_cfg; -mod check_doc_test_visibility; +pub(crate) mod calculate_doc_coverage; +pub(crate) mod check_doc_cfg; +pub(crate) mod check_doc_test_visibility; pub(crate) mod collect_intra_doc_links; -mod collect_trait_impls; -mod lint; -mod propagate_doc_cfg; -mod propagate_stability; -mod strip_aliased_non_local; -mod strip_hidden; -mod strip_priv_imports; -mod strip_private; - -/// A single pass over the cleaned documentation. -/// -/// Runs in the compiler context, so it has access to types and traits and the like. -#[derive(Copy, Clone)] -pub(crate) struct Pass { - pub(crate) name: &'static str, - pub(crate) run: Option) -> clean::Crate>, -} - -/// In a list of passes, a pass that may or may not need to be run depending on options. -#[derive(Copy, Clone)] -pub(crate) struct ConditionalPass { - pub(crate) pass: Pass, - pub(crate) condition: Condition, -} - -/// How to decide whether to run a conditional pass. -#[derive(Copy, Clone)] -pub(crate) enum Condition { - Always, - /// When `--document-private-items` is passed. - WhenDocumentPrivate, - /// When `--document-private-items` is not passed. - WhenNotDocumentPrivate, - /// When `--document-hidden-items` is not passed. - WhenNotDocumentHidden, +pub(crate) mod collect_trait_impls; +pub(crate) mod lint; +pub(crate) mod propagate_doc_cfg; +pub(crate) mod propagate_stability; +pub(crate) mod strip_aliased_non_local; +pub(crate) mod strip_hidden; +pub(crate) mod strip_priv_imports; +pub(crate) mod strip_private; + +macro_rules! initialize { + ($tcx:ident, $cx:ident) => { + macro_rules! track { + ($name:ident($krate:ident)) => {{ + debug!("running pass `{}`", stringify!($name)); + $tcx.sess.time(stringify!($name), || passes::$name::$name($krate, &mut $cx)) + }}; + } + }; } -/// The list of passes run by default. -const DEFAULT_PASSES: &[ConditionalPass] = &[ - ConditionalPass::always(collect_trait_impls::COLLECT_TRAIT_IMPLS), - ConditionalPass::always(check_doc_test_visibility::CHECK_DOC_TEST_VISIBILITY), - ConditionalPass::always(check_doc_cfg::CHECK_DOC_CFG), - ConditionalPass::always(strip_aliased_non_local::STRIP_ALIASED_NON_LOCAL), - ConditionalPass::always(propagate_doc_cfg::PROPAGATE_DOC_CFG), - ConditionalPass::new(strip_hidden::STRIP_HIDDEN, WhenNotDocumentHidden), - ConditionalPass::new(strip_private::STRIP_PRIVATE, WhenNotDocumentPrivate), - ConditionalPass::new(strip_priv_imports::STRIP_PRIV_IMPORTS, WhenDocumentPrivate), - ConditionalPass::always(collect_intra_doc_links::COLLECT_INTRA_DOC_LINKS), - ConditionalPass::always(propagate_stability::PROPAGATE_STABILITY), - ConditionalPass::always(lint::RUN_LINTS), -]; - -/// The list of default passes run when `--doc-coverage` is passed to rustdoc. -const COVERAGE_PASSES: &[ConditionalPass] = &[ - ConditionalPass::new(strip_hidden::STRIP_HIDDEN, WhenNotDocumentHidden), - ConditionalPass::new(strip_private::STRIP_PRIVATE, WhenNotDocumentPrivate), - ConditionalPass::always(calculate_doc_coverage::CALCULATE_DOC_COVERAGE), -]; - -impl ConditionalPass { - pub(crate) const fn always(pass: Pass) -> Self { - Self::new(pass, Always) - } - - pub(crate) const fn new(pass: Pass, condition: Condition) -> Self { - ConditionalPass { pass, condition } - } -} - -/// Returns the given default set of passes. -pub(crate) fn defaults(show_coverage: bool) -> &'static [ConditionalPass] { - if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES } -} +pub(crate) use initialize; diff --git a/src/librustdoc/passes/propagate_doc_cfg.rs b/src/librustdoc/passes/propagate_doc_cfg.rs index 2d12a3979304c..6fda242c00482 100644 --- a/src/librustdoc/passes/propagate_doc_cfg.rs +++ b/src/librustdoc/passes/propagate_doc_cfg.rs @@ -11,10 +11,6 @@ use crate::clean::inline::{load_attrs, merge_attrs}; use crate::clean::{CfgInfo, Crate, Item, ItemKind}; use crate::core::DocContext; use crate::fold::DocFolder; -use crate::passes::Pass; - -pub(crate) const PROPAGATE_DOC_CFG: Pass = - Pass { name: "propagate-doc-cfg", run: Some(propagate_doc_cfg) }; pub(crate) fn propagate_doc_cfg(cr: Crate, cx: &mut DocContext<'_>) -> Crate { if cx.tcx.features().doc_cfg() { diff --git a/src/librustdoc/passes/propagate_stability.rs b/src/librustdoc/passes/propagate_stability.rs index 67c59f794454f..02b9cf85a9bb8 100644 --- a/src/librustdoc/passes/propagate_stability.rs +++ b/src/librustdoc/passes/propagate_stability.rs @@ -12,10 +12,6 @@ use rustc_hir::{Stability, StabilityLevel}; use crate::clean::{Crate, Item, ItemId, ItemKind}; use crate::core::DocContext; use crate::fold::DocFolder; -use crate::passes::Pass; - -pub(crate) const PROPAGATE_STABILITY: Pass = - Pass { name: "propagate-stability", run: Some(propagate_stability) }; pub(crate) fn propagate_stability(cr: Crate, cx: &mut DocContext<'_>) -> Crate { let crate_stability = cx.tcx.lookup_stability(CRATE_DEF_ID); diff --git a/src/librustdoc/passes/strip_aliased_non_local.rs b/src/librustdoc/passes/strip_aliased_non_local.rs index 0e16b56891887..eda2b1eb5872e 100644 --- a/src/librustdoc/passes/strip_aliased_non_local.rs +++ b/src/librustdoc/passes/strip_aliased_non_local.rs @@ -6,12 +6,11 @@ use crate::clean; use crate::clean::Item; use crate::core::DocContext; use crate::fold::{DocFolder, strip_item}; -use crate::passes::Pass; -pub(crate) const STRIP_ALIASED_NON_LOCAL: Pass = - Pass { name: "strip-aliased-non-local", run: Some(strip_aliased_non_local) }; - -fn strip_aliased_non_local(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { +pub(crate) fn strip_aliased_non_local( + krate: clean::Crate, + cx: &mut DocContext<'_>, +) -> clean::Crate { let mut stripper = AliasedNonLocalStripper { tcx: cx.tcx }; stripper.fold_crate(krate) } diff --git a/src/librustdoc/passes/strip_hidden.rs b/src/librustdoc/passes/strip_hidden.rs index 53611e87ef091..a34c69ee43775 100644 --- a/src/librustdoc/passes/strip_hidden.rs +++ b/src/librustdoc/passes/strip_hidden.rs @@ -12,11 +12,13 @@ use crate::clean::utils::inherits_doc_hidden; use crate::clean::{self, Item, ItemIdSet, reexport_chain}; use crate::core::DocContext; use crate::fold::{DocFolder, strip_item}; -use crate::passes::{ImplStripper, Pass}; - -pub(crate) const STRIP_HIDDEN: Pass = Pass { name: "strip-hidden", run: Some(strip_hidden) }; +use crate::passes::ImplStripper; pub(crate) fn strip_hidden(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { + if cx.document_hidden() { + return krate; + } + let mut retained = ItemIdSet::default(); let is_json_output = cx.is_json_output(); diff --git a/src/librustdoc/passes/strip_priv_imports.rs b/src/librustdoc/passes/strip_priv_imports.rs index a0733dde7073d..73586a6f33f32 100644 --- a/src/librustdoc/passes/strip_priv_imports.rs +++ b/src/librustdoc/passes/strip_priv_imports.rs @@ -3,12 +3,14 @@ use crate::clean; use crate::core::DocContext; use crate::fold::DocFolder; -use crate::passes::{ImportStripper, Pass}; - -pub(crate) const STRIP_PRIV_IMPORTS: Pass = - Pass { name: "strip-priv-imports", run: Some(strip_priv_imports) }; +use crate::passes::ImportStripper; pub(crate) fn strip_priv_imports(krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { + if !cx.document_private() { + // We don't need to do anything since it'll be handled by the `strip_private` pass. + return krate; + } + let is_json_output = cx.is_json_output(); ImportStripper { tcx: cx.tcx, is_json_output, document_hidden: cx.document_hidden() } .fold_crate(krate) diff --git a/src/librustdoc/passes/strip_private.rs b/src/librustdoc/passes/strip_private.rs index 2858eabecf3d2..749410893abd5 100644 --- a/src/librustdoc/passes/strip_private.rs +++ b/src/librustdoc/passes/strip_private.rs @@ -5,11 +5,13 @@ use crate::clean::{self, ItemIdSet}; use crate::core::DocContext; use crate::fold::DocFolder; -use crate::passes::{ImplStripper, ImportStripper, Pass, Stripper}; - -pub(crate) const STRIP_PRIVATE: Pass = Pass { name: "strip-private", run: Some(strip_private) }; +use crate::passes::{ImplStripper, ImportStripper, Stripper}; pub(crate) fn strip_private(mut krate: clean::Crate, cx: &mut DocContext<'_>) -> clean::Crate { + if cx.document_private() { + return krate; + } + // This stripper collects all *retained* nodes. let mut retained = ItemIdSet::default(); let is_json_output = cx.is_json_output();