Update doc examples to remove deprecated code and restore testing.

Closes #59.

The doc examples have code interspersed with text explaining the API.  Because
each doctest executes independently, when these code examples are run as
doctests, they have to include parts of the previous examples with # lines.
These lines are hidden from Rustdoc output and do not appear in the rendered
docs, but they do appear when viewing the README.md on Github.

In order to hide these on Github, the code blocks were made non-executable,
with their content moved to a unit test.  However, this meant that the example
API usage was not tested, and so when the unit test was updated to remove the
deprecated `rand_os`, there was no check that the examples stayed in sync with
the test, causing #59.  To prevent this from reocurring in the future, go back
to executable tests of the API examples.

README.md

@@ -31,45 +31,60 @@ the rest of the afternoon nomming some yummy pie!
 First, Alice uses `EphemeralSecret::new()` and then
 `PublicKey::from()` to produce her secret and public keys:
 
-```rust,ignore
-extern crate rand_os;
-extern crate x25519_dalek;
+```rust
+use rand_core::OsRng;
+use x25519_dalek::{EphemeralSecret, PublicKey};
 
-use rand_os::OsRng;
-
-use x25519_dalek::EphemeralSecret;
-use x25519_dalek::PublicKey;
-
-let mut alice_csprng = OsRng::new().unwrap();
-let     alice_secret = EphemeralSecret::new(&mut alice_csprng);
-let     alice_public = PublicKey::from(&alice_secret);
+let alice_secret = EphemeralSecret::new(OsRng);
+let alice_public = PublicKey::from(&alice_secret);
 ```
 
 Bob does the same:
 
-```rust,ignore
-let mut bob_csprng = OsRng::new().unwrap();
-let     bob_secret = EphemeralSecret::new(&mut bob_csprng);
-let     bob_public = PublicKey::from(&bob_secret);
+```rust
+# use rand_core::OsRng;
+# use x25519_dalek::{EphemeralSecret, PublicKey};
+let bob_secret = EphemeralSecret::new(OsRng);
+let bob_public = PublicKey::from(&bob_secret);
 ```
 
 Alice meows across the room, telling `alice_public` to Bob, and Bob
 loudly meows `bob_public` back to Alice.  Alice now computes her
 shared secret with Bob by doing:
 
-```rust,ignore
+```rust
+# use rand_core::OsRng;
+# use x25519_dalek::{EphemeralSecret, PublicKey};
+# let alice_secret = EphemeralSecret::new(OsRng);
+# let alice_public = PublicKey::from(&alice_secret);
+# let bob_secret = EphemeralSecret::new(OsRng);
+# let bob_public = PublicKey::from(&bob_secret);
 let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
 ```
 
 Similarly, Bob computes a shared secret by doing:
 
-```rust,ignore
+```rust
+# use rand_core::OsRng;
+# use x25519_dalek::{EphemeralSecret, PublicKey};
+# let alice_secret = EphemeralSecret::new(OsRng);
+# let alice_public = PublicKey::from(&alice_secret);
+# let bob_secret = EphemeralSecret::new(OsRng);
+# let bob_public = PublicKey::from(&bob_secret);
 let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
 ```
 
 These secrets are the same:
 
-```rust,ignore
+```rust
+# use rand_core::OsRng;
+# use x25519_dalek::{EphemeralSecret, PublicKey};
+# let alice_secret = EphemeralSecret::new(OsRng);
+# let alice_public = PublicKey::from(&alice_secret);
+# let bob_secret = EphemeralSecret::new(OsRng);
+# let bob_public = PublicKey::from(&bob_secret);
+# let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
+# let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
 assert_eq!(alice_shared_secret.as_bytes(), bob_shared_secret.as_bytes());
 ```
 

src/x25519.rs

@@ -199,21 +199,6 @@ mod test {
 
     use rand_core::OsRng;
 
-    // This was previously a doctest but it got moved to the README to
-    // avoid duplication where it then wasn't being run, so now it
-    // lives here.
-    #[test]
-    fn alice_and_bob() {
-        let alice_secret = EphemeralSecret::new(&mut OsRng);
-        let alice_public = PublicKey::from(&alice_secret);
-        let bob_secret = EphemeralSecret::new(&mut OsRng);
-        let bob_public = PublicKey::from(&bob_secret);
-        let alice_shared_secret = alice_secret.diffie_hellman(&bob_public);
-        let bob_shared_secret = bob_secret.diffie_hellman(&alice_public);
-
-        assert_eq!(alice_shared_secret.as_bytes(), bob_shared_secret.as_bytes());
-    }
-
     #[test]
     fn byte_basepoint_matches_edwards_scalar_mul() {
         let mut scalar_bytes = [0x37; 32];