Code change:
From So not sure which way seems better? What do you think ?
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)
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.
Also, there doesn't seem to be a flag. Are you thinking of ? If so, rustdoc says that's deprecated. Edit: It looks like is deprecated as well.
What is "the new stuff"? Do you mean things like ? 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.
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.

Related discussion:
text: Rustdoc has a concept called "passes". These are transformations that `rustdoc` runs on your documentation before producing its final output. <del> In addition to the passes below, check out the docs for these flags: </del> <ins> Customizing passes is **deprecated**. The available passes are not considered stable and may change in any release. </ins> <del> * [`--passes`](command-line-arguments.md#--passes-add-more-rustdoc-passes) * [`--no-defaults`](command-line-arguments.md#--no-defaults-dont-run-default-passes) ## Default passes By default, rustdoc will run some passes, namely: * `strip-hidden` * `strip-private` * `collapse-docs` * `unindent-comments` However, `strip-private` implies `strip-priv-imports`, and so effectively, all passes are run by default. ## `strip-hidden` This pass implements the `#[doc(hidden)]` attribute. When this pass runs, it checks each item, and if it is annotated with this attribute, it removes it from `rustdoc`'s output. Without this pass, these items will remain in the output. ## `unindent-comments` When you write a doc comment like this: ```rust,no_run /// This is a documentation comment. # fn f() {} ``` There's a space between the `///` and that `T`. That spacing isn't intended to be a part of the output; it's there for humans, to help separate the doc comment syntax from the text of the comment. This pass is what removes that space. The exact rules are left under-specified so that we can fix issues that we find. Without this pass, the exact number of spaces is preserved. ## `collapse-docs` With this pass, multiple `#[doc]` attributes are converted into one single documentation string. For example: ```rust,no_run #[doc = "This is the first line."] #[doc = "This is the second line."] # fn f() {} ``` Gets collapsed into a single doc string of ```text This is the first line. This is the second line. ``` ## `strip-private` This removes documentation for any non-public items, so for example: ```rust,no_run /// These are private docs. struct Private; /// These are public docs. pub struct Public; ``` This pass removes the docs for `Private`, since they're not public. This pass implies `strip-priv-imports`. ## `strip-priv-imports` This is the same as `strip-private`, but for `extern crate` and `use` statements instead of items. </del> <ins> In the past the most common use case for customizing passes was to omit the `strip-private` pass. You can do this more easily, and without risk of the pass being changed, by passing [`--document-private-items`](./unstable-features.md#--document-private-items). </ins>