Add documentation for `private_intra_doc_links`

2 files changed, 41 insertions, 1 deletions

diff --git a/compiler/rustc_session/src/lint/builtin.rs b/compiler/rustc_session/src/lint/builtin.rs
index 8c3218b8e80..0cc97fb4541 100644
--- a/compiler/rustc_session/src/lint/builtin.rs
+++ b/compiler/rustc_session/src/lint/builtin.rs
@@ -1831,7 +1831,7 @@ declare_lint! {
     /// a public item to a private one. This is a `rustdoc` only lint, see the
     /// documentation in the [rustdoc book].
     ///
-    /// [rustdoc book]: ../../../rustdoc/lints.html#broken_intra_doc_links
+    /// [rustdoc book]: ../../../rustdoc/lints.html#private_intra_doc_links
     pub PRIVATE_INTRA_DOC_LINKS,
     Warn,
     "linking from a public item to a private one"
diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
index 9ff897710f6..3e632a0644a 100644
--- a/src/doc/rustdoc/src/lints.md
+++ b/src/doc/rustdoc/src/lints.md
@@ -62,6 +62,46 @@ help: to link to the function, add parentheses
 
 ```
 
+## private_intra_doc_links
+
+This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
+For example:
+
+```rust
+/// [private]
+pub fn public() {}
+fn private() {}
+```
+
+This gives a warning that the link will be broken when it appears in your documentation:
+
+```text
+warning: public documentation for `public` links to private item `private`
+ --> priv.rs:1:6
+  |
+1 | /// [private]
+  |      ^^^^^^^ this item is private
+  |
+  = note: `#[warn(private_intra_doc_links)]` on by default
+  = note: this link will resolve properly if you pass `--document-private-items`
+```
+
+Note that this has different behavior depending on whether you pass `--document-private-items` or not!
+If you document private items, then it will still generate a link, despite the warning:
+
+```text
+warning: public documentation for `public` links to private item `private`
+ --> priv.rs:1:6
+  |
+1 | /// [private]
+  |      ^^^^^^^ this item is private
+  |
+  = note: `#[warn(private_intra_doc_links)]` on by default
+  = note: this link resolves only because you passed `--document-private-items`, but will break without
+```
+
+[intra-doc links]: linking-to-items-by-name.html
+
 ## missing_docs
 
 This lint is **allowed by default**. It detects items missing documentation.