From 9e6a9fdcf2b7cd9ae3b901ee7200818a3e66ca52 Mon Sep 17 00:00:00 2001
From: lestrrat <lestrrat@users.noreply.github.com>
Date: Sat, 16 Apr 2022 06:29:46 +0000
Subject: [PATCH] autodoc updates

---
 docs/01-jwt.md |  6 +++---
 docs/02-jws.md |  8 ++++----
 docs/03-jwe.md |  6 +++---
 docs/04-jwk.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/docs/01-jwt.md b/docs/01-jwt.md
index 4f2682832..9bde25f90 100644
--- a/docs/01-jwt.md
+++ b/docs/01-jwt.md
@@ -392,8 +392,8 @@ func ExampleJWT_ParseWithKeySet() {
     // all of the public keys
     {
       privset := jwk.NewSet()
-      privset.Add(realKey)
-      privset.Add(bogusKey)
+      privset.AddKey(realKey)
+      privset.AddKey(bogusKey)
       v, err := jwk.PublicSetOf(privset)
       if err != nil {
         fmt.Printf("failed to create public JWKS: %s\n", err)
@@ -610,7 +610,7 @@ func ExampleJWT_ParseWithJKU() {
       fmt.Printf("failed to create public key: %s\n", err)
       return
     }
-    set.Add(pubkey)
+    set.AddKey(pubkey)
   }
 
   srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
diff --git a/docs/02-jws.md b/docs/02-jws.md
index 7407e83b9..bd3d29d2a 100644
--- a/docs/02-jws.md
+++ b/docs/02-jws.md
@@ -370,14 +370,14 @@ func ExampleJWS_VerifyWithJWKSet() {
   set := jwk.NewSet()
   // Add some bogus keys
   k1, _ := jwk.FromRaw([]byte("abracadavra"))
-  set.Add(k1)
+  set.AddKey(k1)
   k2, _ := jwk.FromRaw([]byte("opensasame"))
-  set.Add(k2)
-  // Add the real thing
+  set.AddKey(k2)
+  // AddKey the real thing
   pubkey, _ := jwk.PublicRawKeyOf(privkey)
   k3, _ := jwk.FromRaw(pubkey)
   k3.Set(jwk.AlgorithmKey, jwa.RS256)
-  set.Add(k3)
+  set.AddKey(k3)
 
   // Up to this point, you probably will replace with a simple jwk.Fetch()
 
diff --git a/docs/03-jwe.md b/docs/03-jwe.md
index bea35d3f9..71ab01e2c 100644
--- a/docs/03-jwe.md
+++ b/docs/03-jwe.md
@@ -416,13 +416,13 @@ func ExampleJWE_VerifyWithJWKSet() {
   set := jwk.NewSet()
   // Add some bogus keys
   k1, _ := jwk.FromRaw([]byte("abracadavra"))
-  set.Add(k1)
+  set.AddKey(k1)
   k2, _ := jwk.FromRaw([]byte("opensasame"))
-  set.Add(k2)
+  set.AddKey(k2)
   // Add the real thing
   k3, _ := jwk.FromRaw(privkey)
   k3.Set(jwk.AlgorithmKey, jwa.RSA_OAEP)
-  set.Add(k3)
+  set.AddKey(k3)
 
   // Up to this point, you probably will replace with a simple jwk.Fetch()
 
diff --git a/docs/04-jwk.md b/docs/04-jwk.md
index 063f0e003..983776554 100644
--- a/docs/04-jwk.md
+++ b/docs/04-jwk.md
@@ -670,6 +670,49 @@ source: [examples/jwk_cache_example_test.go](https://github.com/lestrrat-go/jwx/
 <!-- END INCLUDE -->
 
 <!-- INCLUDE(examples/jwk_cached_set_example_test.go) -->
+```go
+package examples_test
+
+import (
+  "context"
+  "fmt"
+  "time"
+
+  "github.com/lestrrat-go/jwx/v2/jwk"
+  "github.com/lestrrat-go/jwx/v2/jws"
+)
+
+func ExampleJWK_CachedSet() {
+  ctx, cancel := context.WithCancel(context.Background())
+  defer cancel()
+
+  const googleCerts = `https://www.googleapis.com/oauth2/v3/certs`
+
+  // The first steps are the same as examples/jwk_cache_example_test.go
+  c := jwk.NewCache(ctx)
+  c.Register(googleCerts, jwk.WithMinRefreshInterval(15*time.Minute))
+  _, err := c.Refresh(ctx, googleCerts)
+  if err != nil {
+    fmt.Printf("failed to refresh google JWKS: %s\n", err)
+    return
+  }
+
+  cached := jwk.NewCachedSet(c, googleCerts)
+
+  // cached fulfills the jwk.Set interface.
+  var _ jwk.Set = cached
+
+  // That means you can pass it to things like jws.WithKeySet,
+  // allowing you to pretend as if you are using the result of
+  //
+  //   jwk.Fetch(ctx, googleCerts)
+  //
+  // But you are instead using a cached (and periodically refreshed)
+  // for each operation.
+  _ = jws.WithKeySet(cached)
+}
+```
+source: [examples/jwk_cached_set_example_test.go](https://github.com/lestrrat-go/jwx/blob/v2/examples/jwk_cached_set_example_test.go)
 <!-- END INCLUDE -->
 
 ## Using Whitelists