Description
openedon Dec 9, 2021
Currently, rustdoc --passes does one of two things:
--passes listshows a list of available passes:
Available passes for running rustdoc:
check_doc_test_visibility - run various visibility-related lints on doctests
strip-hidden - strips all `#[doc(hidden)]` items from the output
unindent-comments - removes excess indentation on comments in order for markdown to like it
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-doc-cfg - propagates `#[doc(cfg(...))]` to child items
collect-intra-doc-links - resolves intra-doc links
check-code-block-syntax - validates syntax inside Rust code blocks
collect-trait-impls - retrieves trait impls for items in the crate
calculate-doc-coverage - counts the number of items with and without documentation
check-invalid-html-tags - detects invalid HTML tags in doc comments
check-bare-urls - detects URLs that are not hyperlinks
Default passes for rustdoc:
collect-trait-impls
unindent-comments
check_doc_test_visibility
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
check-code-block-syntax
check-invalid-html-tags
propagate-doc-cfg
check-bare-urls
Passes run with `--show-coverage`:
strip-hidden (when not --document-hidden-items)
strip-private (when not --document-private-items)
calculate-doc-coverage
rustdoc --passes collect-trait-implswill add that specific pass to the list of passes rustdoc executes (I think this is intended to be used with--no-defaults, which is also deprecated).
Both of these are stable, so unfortunately we can't remove them; 2. is deprecated and 1. should be soon (after #91713 is fixed). However, this is not a very useful sort of stability, because the names and number of passes is not stable, and rustdoc is very likely to be buggy if you don't run all passes (there's no sort of test for this).
I propose not just deprecating --passes and --no-defaults but making them a no-op altogether, which means less complexity both for users and in the rustdoc codebase. I also suggest removing the CLI help at the same time (and just say "this flag is a no-op").
Note that the only other deprecated flag, --input-format, is also currently a no-op when used with --input-format rust, and a hard error otherwise. We could go further and make everything but --passes=list be a hard error, but that seems like more of a breaking change than necessary for the goal of reducing complexity.
