doc: add a "primitive type reference" page

While it is not useful to list impls here, and there are no inherent methods,
references are still a primitive (and very important) type and should get an
entry in the overview on http://doc.rust-lang.org/std/#primitives and a place
to put general verbiage about references, and probably a reference to the book.

We do *not* add links to this page from other types, like we do for `&[T]`,
because that would likely be more confusing than helpful.

Fixes: rust-lang#15654

Author: birkenfeld

src/librustdoc/clean/mod.rs

@@ -1495,6 +1495,7 @@ pub enum PrimitiveType {
     Array,
     PrimitiveTuple,
     PrimitiveRawPointer,
+    PrimitiveRef,
 }
 
 #[derive(Clone, RustcEncodable, RustcDecodable, Copy, Debug)]
@@ -1573,6 +1574,7 @@ impl PrimitiveType {
             "slice" => Some(Slice),
             "tuple" => Some(PrimitiveTuple),
             "pointer" => Some(PrimitiveRawPointer),
+            "ref" => Some(PrimitiveRef),
             _ => None,
         }
     }
@@ -1611,6 +1613,7 @@ impl PrimitiveType {
             Slice => "slice",
             PrimitiveTuple => "tuple",
             PrimitiveRawPointer => "pointer",
+            PrimitiveRef => "ref",
         }
     }
 
@@ -2350,6 +2353,7 @@ fn build_deref_target_impls(cx: &DocContext,
             Array => tcx.lang_items.slice_impl(),
             PrimitiveTuple => None,
             PrimitiveRawPointer => tcx.lang_items.const_ptr_impl(),
+            PrimitiveRef => None,
         };
         if let Some(did) = did {
             if !did.is_local() {

src/libstd/primitive_docs.rs

@@ -165,6 +165,27 @@ mod prim_char { }
 ///
 mod prim_unit { }
 
+#[doc(primitive = "ref")]
+//
+/// Borrowed references, `&T`, and `&mut T`.
+///
+/// References fundamental to Rust's system of ownership and borrowing. They
+/// are represented as pointers, but the compiler can statically ensure that no
+/// unsafety results from passing and dereferencing them.
+///
+/// Shared references (`&T`) allow read-only access to the pointee, while
+/// mutable references (`&mut T`) allow full access, which is why mutable
+/// references are enforced to be exclusive.
+///
+/// (Point to the section in the book?)
+///
+/// Reference types have no inherent methods. Any methods called on a reference
+/// will be resolved to methods on the pointee. However, traits can be
+/// implemented for reference types. These implementations will show up in the
+/// documentation for the pointee type.
+///
+mod prim_ref { }
+
 #[doc(primitive = "pointer")]
 //
 /// Raw, unsafe pointers, `*const T`, and `*mut T`.