Auto merge of #43560 - QuietMisdreavus:ref-docs, r=steveklabnik

add docs for references as a primitive

Just like #43529 did for function pointers, here is a new primitive page for references.

This PR will pull in impls on references if it's a reference to a generic type parameter. Initially i was only able to pull in impls that were re-exported from another crate; crate-local impls got a different representation in the AST, and i had to change how types were resolved when cleaning it. (This is the change at the bottom of `librustdoc/clean/mod.rs`, in `resolve_type`.) I'm unsure the full ramifications of the change, but from what it looks like, it shouldn't impact anything major. Likewise, references to generic type parameters also get the `&'a [mut]` linked to the new page.

cc @rust-lang/docs: Is this sufficient information? The listing of trait impls kinda feels redundant (especially if we can get the automated impl listing sorted again), but i still think it's useful to point out that you can use these in a generic context.

Fixes #15654

1 files changed, 17 insertions, 19 deletions

diff --git a/src/librustdoc/html/format.rs b/src/librustdoc/html/format.rs
index 766e76137ca..33ab5cf47de 100644
--- a/src/librustdoc/html/format.rs
+++ b/src/librustdoc/html/format.rs
@@ -665,26 +665,29 @@ fn fmt_type(t: &clean::Type, f: &mut fmt::Formatter, use_absolute: bool) -> fmt:
                 _ => "".to_string(),
             };
             let m = MutableSpace(mutability);
+            let amp = if f.alternate() {
+                "&".to_string()
+            } else {
+                "&".to_string()
+            };
             match **ty {
                 clean::Slice(ref bt) => { // BorrowedRef{ ... Slice(T) } is &[T]
                     match **bt {
                         clean::Generic(_) => {
                             if f.alternate() {
                                 primitive_link(f, PrimitiveType::Slice,
-                                    &format!("&{}{}[{:#}]", lt, m, **bt))
+                                    &format!("{}{}{}[{:#}]", amp, lt, m, **bt))
                             } else {
                                 primitive_link(f, PrimitiveType::Slice,
-                                    &format!("&{}{}[{}]", lt, m, **bt))
+                                    &format!("{}{}{}[{}]", amp, lt, m, **bt))
                             }
                         }
                         _ => {
+                            primitive_link(f, PrimitiveType::Slice,
+                                           &format!("{}{}{}[", amp, lt, m))?;
                             if f.alternate() {
-                                primitive_link(f, PrimitiveType::Slice,
-                                               &format!("&{}{}[", lt, m))?;
                                 write!(f, "{:#}", **bt)?;
                             } else {
-                                primitive_link(f, PrimitiveType::Slice,
-                                               &format!("&{}{}[", lt, m))?;
                                 write!(f, "{}", **bt)?;
                             }
                             primitive_link(f, PrimitiveType::Slice, "]")
@@ -692,23 +695,18 @@ fn fmt_type(t: &clean::Type, f: &mut fmt::Formatter, use_absolute: bool) -> fmt:
                     }
                 }
                 clean::ResolvedPath { typarams: Some(ref v), .. } if !v.is_empty() => {
-                    if f.alternate() {
-                        write!(f, "&{}{}", lt, m)?;
-                    } else {
-                        write!(f, "&{}{}", lt, m)?;
-                    }
-                    write!(f, "(")?;
+                    write!(f, "{}{}{}(", amp, lt, m)?;
                     fmt_type(&ty, f, use_absolute)?;
                     write!(f, ")")
                 }
+                clean::Generic(..) => {
+                    primitive_link(f, PrimitiveType::Reference,
+                                   &format!("{}{}{}", amp, lt, m))?;
+                    fmt_type(&ty, f, use_absolute)
+                }
                 _ => {
-                    if f.alternate() {
-                        write!(f, "&{}{}", lt, m)?;
-                        fmt_type(&ty, f, use_absolute)
-                    } else {
-                        write!(f, "&{}{}", lt, m)?;
-                        fmt_type(&ty, f, use_absolute)
-                    }
+                    write!(f, "{}{}{}", amp, lt, m)?;
+                    fmt_type(&ty, f, use_absolute)
                 }
             }
         }