From c6f494baa71029bdec7d16961affba27b1b2c9ae Mon Sep 17 00:00:00 2001
From: Alex Rudy <github@alexrudy.net>
Date: Sun, 26 Nov 2023 05:26:31 +0000
Subject: [PATCH] Fix doctests

---
 README.md        |  2 +-
 src/token/mod.rs | 22 ++++++++++++++--------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 224c8fc..d078223 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ ecosystem.
 
 This is an example [JWT][], taken from the ACME standard ([RFC 8555][RFC8555]):
 
-```
+```json
 {
   "protected": base64url({
     "alg": "ES256",
diff --git a/src/token/mod.rs b/src/token/mod.rs
index 7f1a467..274e5fe 100644
--- a/src/token/mod.rs
+++ b/src/token/mod.rs
@@ -211,27 +211,32 @@ To transition a token from the [`Unsigned`] state to the [`Signed`] state, use t
 
 ```rust
 # use jaws::token::Token;
-let key = rsa::pkcs1v15::SigningKey::random(&mut rand::thread_rng(), 2048).unwrap();
+# use signature::rand_core as rand;
+let key = rsa::pkcs1v15::SigningKey::random(&mut rand::OsRng, 2048).unwrap();
 let token = Token::compact((), ());
 
 // The only way to get a signed token is to sign an Unsigned token!
-let signed = token.sign(&key).unwrap();
-println!("Token: {}", signed.rendered());
+let signed = token.sign::<rsa::pkcs1v15::SigningKey<sha2::Sha256>>(&key).unwrap();
+println!("Token: {}", signed.rendered().unwrap());
 ```
+Signing often requires specifying the algorithm to use. In the example above, we use
+`RS256`, which is the RSA-PKCS1-v1-5 signature algorithm with SHA-256. The algorithm is
+specified by constraining the type of `key` when calling [`Token::sign`].
 
 Signed tokens can become unverified ones by discarding the memory of the key used to sign
 them. This is done with the [`Token::unverify`] method:
 
 ```rust
 # use jaws::token::Token;
-# let key = rsa::pkcs1v15::SigningKey::random(&mut rand::thread_rng(), 2048).unwrap();
+# use signature::rand_core as rand;
+# let key: rsa::pkcs1v15::SigningKey<sha2::Sha256> = rsa::pkcs1v15::SigningKey::random(&mut rand::OsRng, 2048).unwrap();
 # let token = Token::compact((), ());
 # let signed = token.sign(&key).unwrap();
 // We can unverify the token, which discard the memory of the key used to sign it.
 let unverified = signed.unverify();
 
 // Unverified tokens still have a signature, but it is no longer considered valid.
-println!("Token: {}", unverified.rendered());
+println!("Token: {}", unverified.rendered().unwrap());
 ```
 
 Tokens can also be transitioned from the [`Unverified`] state to the [`Verified`] state
@@ -240,13 +245,14 @@ by checking the signature. This is done with the [`Token::verify`] method:
 ```rust
 # use jaws::token::Token;
 # use signature::Keypair;
-# let key = rsa::pkcs1v15::SigningKey::random(&mut rand::thread_rng(), 2048).unwrap();
-# let verifying_key = key.verifying_key()
+# use signature::rand_core as rand;
+# let key: rsa::pkcs1v15::SigningKey<sha2::Sha256> = rsa::pkcs1v15::SigningKey::random(&mut rand::OsRng, 2048).unwrap();
+# let verifying_key = key.verifying_key();
 # let token = Token::compact((), ());
 # let signed = token.sign(&key).unwrap();
 # let unverified = signed.unverify();
 let verified = unverified.verify(&verifying_key).unwrap();
-println!("Token: {}", verified.rendered());
+println!("Token: {}", verified.rendered().unwrap());
 ```
 
 Verification can fail if the signature is invalid, or if the algorithm does not match the