Reconcile docs and code, adding examples and adding RESTR_CLAIM

src/test/compile-fail/borrowck-alias-mut-base-ptr.rs

@@ -0,0 +1,15 @@
+// Test that attempt to alias `&mut` pointer while pointee is borrowed
+// yields an error.
+//
+// Example from src/middle/borrowck/doc.rs
+
+use std::util::swap;
+
+fn foo(t0: &mut int) {
+    let p: &int = &*t0; // Freezes `*t0`
+    let q: &const &mut int = &const t0; //~ ERROR cannot borrow `t0`
+    **q = 22; //~ ERROR cannot assign to an `&mut` in a `&const` pointer
+}
+
+fn main() {
+}

src/test/compile-fail/borrowck-borrow-mut-base-ptr-in-aliasable-loc.rs

@@ -0,0 +1,31 @@
+// Test that attempt to reborrow an `&mut` pointer in an aliasable
+// location yields an error.
+//
+// Example from src/middle/borrowck/doc.rs
+
+use std::util::swap;
+
+fn foo(t0: & &mut int) {
+    let t1 = t0;
+    let p: &int = &**t0; //~ ERROR cannot borrow an `&mut` in a `&` pointer
+    **t1 = 22; //~ ERROR cannot assign
+}
+
+fn foo2(t0: &const &mut int) {
+    // Note: reborrowing from an &const actually yields two errors, since it
+    // is unsafe in two ways: we can't control the aliasing, and we can't
+    // control the mutation.
+    let t1 = t0;
+    let p: &int = &**t0; //~ ERROR cannot borrow an `&mut` in a `&const` pointer
+    //~^ ERROR unsafe borrow of aliasable, const value
+    **t1 = 22; //~ ERROR cannot assign
+}
+
+fn foo3(t0: &mut &mut int) {
+    let t1 = &mut *t0;
+    let p: &int = &**t0; //~ ERROR cannot borrow
+    **t1 = 22;
+}
+
+fn main() {
+}

src/test/compile-fail/borrowck-move-mut-base-ptr.rs

@@ -0,0 +1,15 @@
+// Test that attempt to move `&mut` pointer while pointee is borrowed
+// yields an error.
+//
+// Example from src/middle/borrowck/doc.rs
+
+use std::util::swap;
+
+fn foo(t0: &mut int) {
+    let p: &int = &*t0; // Freezes `*t0`
+    let t1 = t0;        //~ ERROR cannot move out of `t0`
+    *t1 = 22;
+}
+
+fn main() {
+}

src/test/compile-fail/borrowck-swap-mut-base-ptr.rs

@@ -0,0 +1,16 @@
+// Test that attempt to swap `&mut` pointer while pointee is borrowed
+// yields an error.
+//
+// Example from src/middle/borrowck/doc.rs
+
+use std::util::swap;
+
+fn foo<'a>(mut t0: &'a mut int,
+           mut t1: &'a mut int) {
+    let p: &int = &*t0;     // Freezes `*t0`
+    swap(&mut t0, &mut t1); //~ ERROR cannot borrow `t0`
+    *t1 = 22;
+}
+
+fn main() {
+}