Extend intra-doc link chapter in the rustdoc book

1 files changed, 18 insertions, 0 deletions

diff --git a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
index 72157b5cd9b..f7a749744e0 100644
--- a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
+++ b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
@@ -151,3 +151,21 @@ will be given, even if the link fails to resolve. For example, any link containi
 characters will be ignored.
 
 [#72243]: https://github.com/rust-lang/rust/issues/72243
+
+## What happens in case an intra-doc link cannot be generated
+
+In some cases (items behind a `cfg` for example), an intra-doc link cannot be generated to item.
+There are different ways to create a link in markdown, and depending on the one you use, it will
+render differently in this case:
+
+```md
+1. [a]
+2. [b][c]
+3. [d](e)
+4. [f]
+
+[f]: g
+```
+
+`1.` and `2.` will will be displayed as is in the rendered documentation (ie, `[a]` and `[b][c]`)
+whereas `3.` and `4.` will be replaced by a link targetting `e` for `[d](e)` and `g` for `[f]`.