Rollup merge of #82690 - jyn514:remove-pass-docs, r=Manishearth

Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.

Closes #82675.

r? `@Manishearth`

Author: GuillaumeGomez

src/doc/rustdoc/src/SUMMARY.md

@@ -8,7 +8,7 @@
 - [Documentation tests](documentation-tests.md)
 - [Linking to items by name](linking-to-items-by-name.md)
 - [Lints](lints.md)
-- [Passes](passes.md)
 - [Advanced features](advanced-features.md)
 - [Unstable features](unstable-features.md)
+- [Passes](passes.md)
 - [References](references.md)

src/doc/rustdoc/src/command-line-arguments.md

@@ -57,23 +57,6 @@ release: 1.17.0
 LLVM version: 3.9
 ```
 
-## `-r`/`--input-format`: input format
-
-This flag is currently ignored; the idea is that `rustdoc` would support various
-input formats, and you could specify them via this flag.
-
-Rustdoc only supports Rust source code and Markdown input formats. If the
-file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
-Otherwise, it assumes that the input file is Rust.
-
-
-## `-w`/`--output-format`: output format
-
-This flag is currently ignored; the idea is that `rustdoc` would support
-various output formats, and you could specify them via this flag.
-
-Rustdoc only supports HTML output, and so this flag is redundant today.
-
 ## `-o`/`--output`: output path
 
 Using this flag looks like this:
@@ -100,6 +83,25 @@ By default, `rustdoc` assumes that the name of your crate is the same name
 as the `.rs` file. `--crate-name` lets you override this assumption with
 whatever name you choose.
 
+## `--document-private-items`: Show items that are not public
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --document-private-items
+```
+
+By default, `rustdoc` only documents items that are publicly reachable.
+
+```rust
+pub fn public() {} // this item is public and will documented
+mod private { // this item is private and will not be documented
+    pub fn unreachable() {} // this item is public, but unreachable, so it will not be documented
+}
+```
+
+`--document-private-items` documents all items, even if they're not public.
+
 ## `-L`/`--library-path`: where to look for dependencies
 
 Using this flag looks like this:
@@ -166,38 +168,6 @@ affect that.
 The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
 get the full list.
 
-## `--passes`: add more rustdoc passes
-
-Using this flag looks like this:
-
-```bash
-$ rustdoc --passes list
-$ rustdoc src/lib.rs --passes strip-priv-imports
-```
-
-An argument of "list" will print a list of possible "rustdoc passes", and other
-arguments will be the name of which passes to run in addition to the defaults.
-
-For more details on passes, see [the chapter on them](passes.md).
-
-See also `--no-defaults`.
-
-## `--no-defaults`: don't run default passes
-
-Using this flag looks like this:
-
-```bash
-$ rustdoc src/lib.rs --no-defaults
-```
-
-By default, `rustdoc` will run several passes over your code. This
-removes those defaults, allowing you to use `--passes` to specify
-exactly which passes you want.
-
-For more details on passes, see [the chapter on them](passes.md).
-
-See also `--passes`.
-
 ## `--test`: run code examples as tests
 
 Using this flag looks like this:
@@ -429,3 +399,21 @@ If you specify `@path` on the command-line, then it will open `path` and read
 command line options from it. These options are one per line; a blank line indicates
 an empty option. The file can use Unix or Windows style line endings, and must be
 encoded as UTF-8.
+
+## `--passes`: add more rustdoc passes
+
+This flag is **deprecated**.
+For more details on passes, see [the chapter on them](passes.md).
+
+## `--no-defaults`: don't run default passes
+
+This flag is **deprecated**.
+For more details on passes, see [the chapter on them](passes.md).
+
+## `-r`/`--input-format`: input format
+
+This flag is **deprecated** and **has no effect**.
+
+Rustdoc only supports Rust source code and Markdown input formats. If the
+file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
+Otherwise, it assumes that the input file is Rust.

src/doc/rustdoc/src/passes.md

@@ -3,86 +3,9 @@
 Rustdoc has a concept called "passes". These are transformations that
 `rustdoc` runs on your documentation before producing its final output.
 
-In addition to the passes below, check out the docs for these flags:
+Customizing passes is **deprecated**. The available passes are not considered stable and may
+change in any release.
 
-* [`--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.
+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).

src/doc/rustdoc/src/unstable-features.md

@@ -340,6 +340,30 @@ Some methodology notes about what rustdoc counts in this metric:
 Public items that are not documented can be seen with the built-in `missing_docs` lint. Private
 items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint.
 
+## `-w`/`--output-format`: output format
+
+When using
+[`--show-coverage`](https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--show-coverage-get-statistics-about-code-documentation-coverage),
+passing `--output-format json` will display the coverage information in JSON format. For example,
+here is the JSON for a file with one documented item and one undocumented item:
+
+```rust
+/// This item has documentation
+pub fn foo() {}
+
+pub fn no_documentation() {}
+```
+
+```json
+{"no_std.rs":{"total":3,"with_docs":1,"total_examples":3,"with_examples":0}}
+```
+
+Note that the third item is the crate root, which in this case is undocumented.
+
+When not using `--show-coverage`, `--output-format json` emits documentation in the experimental
+[JSON format](https://github.com/rust-lang/rfcs/pull/2963). `--output-format html` has no effect,
+and is also accepted on stable toolchains.
+
 ### `--enable-per-target-ignores`: allow `ignore-foo` style filters for doctests
 
 Using this flag looks like this: