autodoc updates (#696)

Co-authored-by: lestrrat <lestrrat@users.noreply.github.com>
lestrrat-go · Apr 16, 2022 · ef5c8ec · ef5c8ec
1 parent dc76d70
commit ef5c8ec
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 10 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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