Make rustdoc --passes and rustdoc --no-defaults have no effect

[jyn514]

Currently, rustdoc --passes does one of two things:

1. --passes list shows 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

2. rustdoc --passes collect-trait-impls will 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.

[jyn514]

@rfcbot fcp merge

[rfcbot]

Team member @jyn514 has proposed to merge this. The next step is review by the rest of the tagged team members:

• @CraftSpider
• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @camelid
• @jsha
• @jyn514
• @ollie27

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[jyn514]

Oh, I forgot to mention earlier - there's precedent for doing this for other deprecated flags:

$ rustdoc --help
        --plugin-path DIR
                        removed
$ rustdoc --plugin-path x
warning: the 'plugin-path' flag no longer functions
  |
  = warning: see CVE-2018-1000622

[camelid]

@rfcbot reviewed

+1. I've been wanting to get rid of these flags for a while.

Should we use a future-incompatibility warning so that it'd be more feasible to potentially remove the flags in the future?

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.

Why everything except --passes=list?

[jyn514]

Should we use a future-incompatibility warning so that it'd be more feasible to potentially remove the flags in the future?

I don't have any objection to doing that, but I don't think it's a big deal either way - the main advantage of future-incompat warnings is they're shown for dependencies, but there's no way to pass flags to a dependency without also passing them to the main crate.

[camelid]

the main advantage of future-incompat warnings is they're shown for dependencies

I meant more that it would signal that you really shouldn't be using these flags and thus make it easier to potentially remove in the future.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[jyn514]

Mentoring instructions: remove manual_passes (and recursively, all code that uses it):

rust/src/librustdoc/config.rs

Lines 130 to 138 in 8f117a7

	// Options that affect the documentation process
	/// The selected default set of passes to use.
	///
	/// Be aware: This option can come both from the CLI and from crate attributes!
	crate default_passes: DefaultPassOption,
	/// Any passes manually selected by the user.
	///
	/// Be aware: This option can come both from the CLI and from crate attributes!
	crate manual_passes: Vec<String>,

Also remove DefaultPassOption::None:

rust/src/librustdoc/config.rs

Line 609 in 8f117a7

passes::DefaultPassOption::None

[pitaj]

@rustbot claim

[camelid]

cc #82824

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.