Add explanations for auto-disambiguation when an intra doc link is resolved to a proc-macro and a trait at the same time

1 files changed, 7 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 36bc312b9c9..eb2285ef906 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
@@ -103,6 +103,13 @@ macro_rules! foo {
 }
 ```
 
+There is one case where the disambiguation will be performed automatically: if an intra doc
+link is resolved at the same time as a trait and as a derive proc-macro. In this case, it'll
+always generate a link to the trait and not emit a "missing disambiguation" warning. A good
+example of this case is when you link to the `Clone` trait: there is also a `Clone`
+proc-macro but it ignores it in this case. If you want to link to the proc-macro, you can
+use the `macro@` disambiguator.
+
 ## Warnings, re-exports, and scoping
 
 Links are resolved in the scope of the module where the item is defined, even