From 8287798aa12ef2147f785429a8f7325a4f2f0513 Mon Sep 17 00:00:00 2001
From: Henry de Valence <hdevalence@hdevalence.ca>
Date: Mon, 17 Aug 2020 18:47:31 -0700
Subject: [PATCH] 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     | 51 +++++++++++++++++++++++++++++++++------------------
 src/x25519.rs | 15 ---------------
 2 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index ff34263..28289be 100644
--- a/README.md
+++ b/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());
 ```
 
diff --git a/src/x25519.rs b/src/x25519.rs
index 6b18781..8866cd5 100644
--- a/src/x25519.rs
+++ b/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];