From 1d10e1acf6cc8e519d4119cb61d266eb0e517268 Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Wed, 15 Dec 2021 18:59:00 -0800 Subject: [PATCH] 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 --- src/librustdoc/passes/bare_urls.rs | 2 ++ src/librustdoc/passes/calculate_doc_coverage.rs | 1 + src/librustdoc/passes/check_code_block_syntax.rs | 1 + src/librustdoc/passes/check_doc_test_visibility.rs | 2 ++ src/librustdoc/passes/collect_trait_impls.rs | 3 +++ src/librustdoc/passes/html_tags.rs | 1 + src/librustdoc/passes/propagate_doc_cfg.rs | 1 + src/librustdoc/passes/strip_hidden.rs | 1 + src/librustdoc/passes/strip_priv_imports.rs | 2 ++ src/librustdoc/passes/strip_private.rs | 2 ++ src/librustdoc/passes/stripper.rs | 1 + src/librustdoc/passes/unindent_comments.rs | 13 +++++++++++++ 12 files changed, 30 insertions(+) diff --git a/src/librustdoc/passes/bare_urls.rs b/src/librustdoc/passes/bare_urls.rs index 4e146a07d154a..3410f46e2a8d2 100644 --- a/src/librustdoc/passes/bare_urls.rs +++ b/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 .` to linkify it. use super::Pass; use crate::clean::*; use crate::core::DocContext; diff --git a/src/librustdoc/passes/calculate_doc_coverage.rs b/src/librustdoc/passes/calculate_doc_coverage.rs index 85542ebd9ac55..6111c982de922 100644 --- a/src/librustdoc/passes/calculate_doc_coverage.rs +++ b/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}; diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs index fd2ab0dc97cb2..a50bf558bf3d1 100644 --- a/src/librustdoc/passes/check_code_block_syntax.rs +++ b/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; diff --git a/src/librustdoc/passes/check_doc_test_visibility.rs b/src/librustdoc/passes/check_doc_test_visibility.rs index 7d3010cf3325b..b86ec8abefaae 100644 --- a/src/librustdoc/passes/check_doc_test_visibility.rs +++ b/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. diff --git a/src/librustdoc/passes/collect_trait_impls.rs b/src/librustdoc/passes/collect_trait_impls.rs index 8524f872ca364..baa0c7595eb86 100644 --- a/src/librustdoc/passes/collect_trait_impls.rs +++ b/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; diff --git a/src/librustdoc/passes/html_tags.rs b/src/librustdoc/passes/html_tags.rs index 56b222d893262..f7a9a0899e390 100644 --- a/src/librustdoc/passes/html_tags.rs +++ b/src/librustdoc/passes/html_tags.rs @@ -1,3 +1,4 @@ +//! Detects invalid HTML (like an unclosed ``) in doc comments. use super::Pass; use crate::clean::*; use crate::core::DocContext; diff --git a/src/librustdoc/passes/propagate_doc_cfg.rs b/src/librustdoc/passes/propagate_doc_cfg.rs index f5a362bfbe8c6..d3df2d2794b42 100644 --- a/src/librustdoc/passes/propagate_doc_cfg.rs +++ b/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; diff --git a/src/librustdoc/passes/strip_hidden.rs b/src/librustdoc/passes/strip_hidden.rs index 0aedbda35e9a8..e63534659add7 100644 --- a/src/librustdoc/passes/strip_hidden.rs +++ b/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; diff --git a/src/librustdoc/passes/strip_priv_imports.rs b/src/librustdoc/passes/strip_priv_imports.rs index 63869324cb8d2..21ce9ae7a28e1 100644 --- a/src/librustdoc/passes/strip_priv_imports.rs +++ b/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; diff --git a/src/librustdoc/passes/strip_private.rs b/src/librustdoc/passes/strip_private.rs index dfdba2a4b3666..c6b5bec4692dc 100644 --- a/src/librustdoc/passes/strip_private.rs +++ b/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; diff --git a/src/librustdoc/passes/stripper.rs b/src/librustdoc/passes/stripper.rs index 74a9a2da06d36..675443b48a206 100644 --- a/src/librustdoc/passes/stripper.rs +++ b/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; diff --git a/src/librustdoc/passes/unindent_comments.rs b/src/librustdoc/passes/unindent_comments.rs index 97f4f941e0686..6cac31d2f90dc 100644 --- a/src/librustdoc/passes/unindent_comments.rs +++ b/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;