Rollup merge of #132876 - lolbinarycat:rustdoc-document-hidden-items, r=GuillaumeGomez

rustdoc book: acknowledge --document-hidden-items

3 files changed, 23 insertions, 4 deletions

diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md
index 1af5e2b0e1d..872592d669d 100644
--- a/src/doc/rustdoc/src/command-line-arguments.md
+++ b/src/doc/rustdoc/src/command-line-arguments.md
@@ -100,7 +100,8 @@ mod private { // this item is private and will not be documented
 }
 ```
 
-`--document-private-items` documents all items, even if they're not public.
+`--document-private-items` includes all non-public items in the generated documentation except for `#[doc(hidden)]` items.  Private items will be shown with a 🔒 icon.
+
 
 ## `-L`/`--library-path`: where to look for dependencies
 
diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
index 3abd538d372..d4ff69a9933 100644
--- a/src/doc/rustdoc/src/unstable-features.md
+++ b/src/doc/rustdoc/src/unstable-features.md
@@ -262,6 +262,25 @@ themselves marked as unstable. To use any of these options, pass `-Z unstable-op
 the flag in question to Rustdoc on the command-line. To do this from Cargo, you can either use the
 `RUSTDOCFLAGS` environment variable or the `cargo rustdoc` command.
 
+### `--document-hidden-items`: Show items that are `#[doc(hidden)]`
+<span id="document-hidden-items"></span>
+
+By default, `rustdoc` does not document items that are annotated with
+[`#[doc(hidden)]`](write-documentation/the-doc-attribute.html#hidden).
+
+`--document-hidden-items` causes all items to be documented as if they did not have `#[doc(hidden)]`, except that hidden items will be shown with a 👻 icon.
+
+Here is a table that fully describes which items are documented with each combination of `--document-hidden-items` and `--document-private-items`:
+
+
+| rustdoc flags                   | items that will be documented         |
+|---------------------------------|---------------------------------------|
+| neither flag                    | only public items that are not hidden |
+| only `--document-hidden-items`  | all public items                      |
+| only `--document-private-items` | all items that are not hidden         |
+| both flags                      | all items                             |
+
+
 ### `--markdown-before-content`: include rendered Markdown before the content
 
  * Tracking issue: [#44027](https://github.com/rust-lang/rust/issues/44027)
diff --git a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
index ff033aa14b8..45146993371 100644
--- a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
+++ b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md
@@ -230,9 +230,8 @@ If you want to know more about inlining rules, take a look at the
 
 <span id="dochidden"></span>
 
-Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless
-the `strip-hidden` pass is removed. Re-exported items where one of its ancestors has
-`#[doc(hidden)]` will be considered the same as private.
+Any item annotated with `#[doc(hidden)]` will not appear in the documentation,
+unless the [`--document-hidden-items`](../unstable-features.md#document-hidden-items) flag is used.
 
 You can find more information in the [`re-exports` chapter](./re-exports.md).