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

Author: jsha

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;