Rollup merge of rust-lang#91987 - jsha:docdocgoose, r=jyn514

Add module documentation for rustdoc passes

These are currently documented at https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html#hot-potato but can easily go out of date. We'd like to document them in place and link to https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/passes/index.html

[Discussed on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/moving.20pass.20docs/near/265058351).

r? `@camelid`

Author: matthiaskrgr

src/librustdoc/passes/bare_urls.rs

@@ -1,3 +1,5 @@
+//! Detects links that are not linkified, e.g., in Markdown such as `Go to https://example.com/.`
+//! Suggests wrapping the link with angle brackets: `Go to <https://example.com/>.` to linkify it.
 use super::Pass;
 use crate::clean::*;
 use crate::core::DocContext;

src/librustdoc/passes/calculate_doc_coverage.rs

@@ -1,3 +1,4 @@
+//! Calculates information used for the --show-coverage flag.
 use crate::clean;
 use crate::core::DocContext;
 use crate::html::markdown::{find_testable_code, ErrorCodes};

src/librustdoc/passes/check_code_block_syntax.rs

@@ -1,3 +1,4 @@
+//! Validates syntax inside Rust code blocks (\`\`\`rust).
 use rustc_data_structures::sync::{Lock, Lrc};
 use rustc_errors::{emitter::Emitter, Applicability, Diagnostic, Handler};
 use rustc_middle::lint::LintDiagnosticBuilder;

src/librustdoc/passes/check_doc_test_visibility.rs

@@ -1,3 +1,5 @@
+//! Looks for items missing (or incorrectly having) doctests.
+//!
 //! This pass is overloaded and runs two different lints.
 //!
 //! - MISSING_DOC_CODE_EXAMPLES: this lint is **UNSTABLE** and looks for public items missing doctests.

src/librustdoc/passes/collect_trait_impls.rs

@@ -1,3 +1,6 @@
+//! 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 super::Pass;
 use crate::clean::*;
 use crate::core::DocContext;

src/librustdoc/passes/html_tags.rs

@@ -1,3 +1,4 @@
+//! Detects invalid HTML (like an unclosed `<span>`) in doc comments.
 use super::Pass;
 use crate::clean::*;
 use crate::core::DocContext;

src/librustdoc/passes/propagate_doc_cfg.rs

@@ -1,3 +1,4 @@
+//! Propagates [`#[doc(cfg(...))]`](https://github.com/rust-lang/rust/issues/43781) to child items.
 use std::sync::Arc;
 
 use crate::clean::cfg::Cfg;

src/librustdoc/passes/strip_hidden.rs

@@ -1,3 +1,4 @@
+//! Strip all doc(hidden) items from the output.
 use rustc_span::symbol::sym;
 use std::mem;
 

src/librustdoc/passes/strip_priv_imports.rs

@@ -1,3 +1,5 @@
+//! Strips all private import statements (use, extern crate) from a
+//! crate.
 use crate::clean;
 use crate::core::DocContext;
 use crate::fold::DocFolder;

src/librustdoc/passes/strip_private.rs

@@ -1,3 +1,5 @@
+//! 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.
 use crate::clean::{self, ItemIdSet};
 use crate::core::DocContext;
 use crate::fold::DocFolder;

src/librustdoc/passes/stripper.rs

@@ -1,3 +1,4 @@
+//! A collection of utility functions for the `strip_*` passes.
 use rustc_hir::def_id::DefId;
 use rustc_middle::middle::privacy::AccessLevels;
 use std::mem;

src/librustdoc/passes/unindent_comments.rs

@@ -1,3 +1,16 @@
+//! Removes excess indentation on comments in order for the Markdown
+//! to be parsed correctly. This is necessary because the convention for
+//! writing documentation is to provide a space between the /// or //! marker
+//! and the doc text, but Markdown is whitespace-sensitive. For example,
+//! a block of text with four-space indentation is parsed as a code block,
+//! so if we didn't unindent comments, these list items
+//!
+//! /// A list:
+//! ///
+//! ///    - Foo
+//! ///    - Bar
+//!
+//! would be parsed as if they were in a code block, which is likely not what the user intended.
 use std::cmp;
 
 use rustc_span::symbol::kw;