Document no_default_passes attribute or remove documentation for --passes and --no-default-passes?

[GuillaumeGomez]

From #82662 (comment).

The whole https://doc.rust-lang.org/nightly/rustdoc/passes.html chapter looks questionable now that customizing passes is deprecated.

So not sure which way seems better? What do you think @rust-lang/rustdoc ?

[Manishearth]

Yeah I think we should document the new stuff and remove the docs for the deprecated stuff (perhaps mention that these deprecated features exist, but not document them in depth)

[camelid]

I've felt confused about this before: Why do we even let people customize which passes are run? That seems like unnecessary entanglement with rustdoc internals.

[camelid]

Also, there doesn't seem to be a --no-default-passes flag. Are you thinking of --no-defaults? If so, rustdoc says that's deprecated.

Edit: It looks like --passes is deprecated as well.

[camelid]

Yeah I think we should document the new stuff and remove the docs for the deprecated stuff (perhaps mention that these deprecated features exist, but not document them in depth)

What is "the new stuff"? Do you mean things like --document-private-items? Other than my confusion about that, I agree with Manish here. I think we should mention the deprecated features, but not document them extensively since they shouldn't be used anyway. If we extensively document deprecated features, we are wasting our time and our readers' time.

[Manishearth]

What is "the new stuff"? Do you mean things like --document-private-items?

Yes.

I do think the pass infra should stay mostly internal, with specific options being exposed via specific attributes. How we construct it internally should not be something the user should ever have to care about.