autodoc updates (#1301)

Co-authored-by: lestrrat <[email protected]>
lestrrat-go · Feb 24, 2025 · 15393b1 · 15393b1
1 parent a3cd476
commit 15393b1
Show file tree

Hide file tree

Showing 6 changed files with 56 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWX() {
+func Example_jwx_readme() {
   // Parse, serialize, slice and dice JWKs!
   privkey, err := jwk.ParseKey(jsonRSAPrivateKey)
   if err != nil {

diff --git a/docs/01-jwt.md b/docs/01-jwt.md
@@ -81,7 +81,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_Parse() {
+func Example_jwt_parse() {
   tok, err := jwt.Parse(jwtSignedWithHS256, jwt.WithKey(jwa.HS256, jwkSymmetricKey))
   if err != nil {
     fmt.Printf("%s\n", err)
@@ -112,7 +112,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ReadFile() {
+func Example_jwt_readfile() {
   f, err := os.CreateTemp(``, `jwt_readfile-*.jws`)
   if err != nil {
     fmt.Printf("failed to create temporary file: %s\n", err)
@@ -154,7 +154,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ParseRequest_Authorization() {
+func Example_jwt_parse_request_authorization() {
   req, err := http.NewRequest(http.MethodGet, `https://github.com/lestrrat-go/jwx`, nil)
   if err != nil {
     fmt.Printf("failed to create request: %s\n", err)
@@ -239,7 +239,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_Construct() {
+func Example_jwt_construct() {
   tok := jwt.New()
   if err := tok.Set(jwt.IssuerKey, `github.com/lestrrat-go/jwx`); err != nil {
     fmt.Printf("failed to set claim: %s\n", err)
@@ -284,7 +284,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_Builder() {
+func Example_jwt_builder() {
   tok, err := jwt.NewBuilder().
     Claim(`claim1`, `value1`).
     Claim(`claim2`, `value2`).
@@ -324,7 +324,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ParseWithKey() {
+func Example_jwt_parse_with_key() {
   const keysrc = `{"kty":"oct","k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"}`
 
   key, err := jwk.ParseKey([]byte(keysrc))
@@ -369,7 +369,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ParseWithKeySet() {
+func Example_jwt_parse_with_keyset() {
   var serialized []byte
   var signingKey jwk.Key
   var keyset jwk.Set
@@ -512,7 +512,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ParseWithKeyProvider_UseToken() {
+func Example_jwt_parse_with_key_provider_use_token() {
   // This example shows how one might use the information in the JWT to
   // load different keys.
 
@@ -581,7 +581,7 @@ func ExampleJWT_ParseWithKeyProvider_UseToken() {
   //
 }
 
-func ExampleJWT_ParseWithKeyProvider() {
+func Example_jwt_parse_with_key_provider() {
   // Pretend that this is a storage somewhere (maybe a database) that maps
   // a signature algorithm to a key
   store := make(map[jwa.KeyAlgorithm]interface{})
@@ -666,7 +666,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ParseWithJKU() {
+func Example_jwt_parse_with_jku() {
   set := jwk.NewSet()
 
   var signingKey jwk.Key
@@ -753,7 +753,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_Validate() {
+func Example_validate_jwt() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     Expiration(time.Now().Add(-1 * time.Hour)).
@@ -813,7 +813,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ValidateIssuer() {
+func Example_jwt_validate_issuer() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     Expiration(time.Now().Add(time.Hour)).
@@ -853,7 +853,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ValidateValidator() {
+func Example_jwt_validate_validator() {
   validator := jwt.ValidatorFunc(func(_ context.Context, t jwt.Token) jwt.ValidationError {
     if t.IssuedAt().Month() != 8 {
       return jwt.NewValidationError(errors.New(`tokens are only valid if issued during August!`))
@@ -900,7 +900,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_ValidateDetectErrorType() {
+func Example_jwt_validate_detect_error_type() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     Expiration(time.Now().Add(-1 * time.Hour)).
@@ -982,7 +982,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_SerializeJSON() {
+func Example_jwt_serialize_json() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     IssuedAt(time.Unix(aLongLongTimeAgo, 0)).
@@ -1019,7 +1019,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_SerializeJWS() {
+func Example_jwt_serialize_jws() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     IssuedAt(time.Unix(aLongLongTimeAgo, 0)).
@@ -1085,7 +1085,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_SerializeJWEJWS() {
+func Example_jwt_serialize_jwe_and_jws() {
   tok, err := jwt.NewBuilder().
     Issuer(`github.com/lestrrat-go/jwx`).
     IssuedAt(time.Unix(aLongLongTimeAgo, 0)).
@@ -1164,7 +1164,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWT_FlattenAudience() {
+func Example_jwt_flatten_audience() {
   // Sometimes you need to "flatten" the "aud" claim because of
   // parsers developed by people who apparently didn't read the RFC.
   //
@@ -1262,7 +1262,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWTPlainStruct() {
+func Example_jwt_plain_struct() {
   t1, err := jwt.NewBuilder().
     Issuer("https://github.com/lestrrat-go/jwx/v2/examples").
     Subject("raw_struct").

diff --git a/docs/02-jws.md b/docs/02-jws.md
@@ -47,7 +47,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_Parse() {
+func Example_jws_parse() {
   const src = `eyJhbGciOiJIUzI1NiJ9.TG9yZW0gaXBzdW0.idbECxA8ZhQbU0ddZmzdRZxQmHjwvw77lT2bwqGgNMo`
 
   msg, err := jws.Parse([]byte(src))
@@ -80,7 +80,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_ReadFile() {
+func Example_jws_readfile() {
   const src = `eyJhbGciOiJIUzI1NiJ9.TG9yZW0gaXBzdW0.idbECxA8ZhQbU0ddZmzdRZxQmHjwvw77lT2bwqGgNMo`
   f, err := os.CreateTemp(``, `jws_readfile-*.jws`)
   if err != nil {
@@ -128,7 +128,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwt"
 )
 
-func ExampleJWS_UseJWSHeader() {
+func Example_jws_use_header() {
   key, err := jwk.FromRaw([]byte(`abracadabra`))
   if err != nil {
     fmt.Printf(`failed to create new symmetric key: %s`, err)
@@ -188,7 +188,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_Sign() {
+func Example_jws_sign() {
   key, err := jwk.FromRaw([]byte(`abracadabra`))
   if err != nil {
     fmt.Printf("failed to create key: %s\n", err)
@@ -226,7 +226,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_SignJSON() {
+func Example_jws_sign_json() {
   var keys []jwk.Key
 
   for i := 0; i < 3; i++ {
@@ -273,7 +273,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_SignDetachedPayload() {
+func Example_jws_sign_detached_payload() {
   payload := `$.02`
 
   key, err := jwk.FromRaw([]byte(`abracadabra`))
@@ -316,7 +316,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_SignWithHeaders() {
+func Example_jws_sign_with_headers() {
   key, err := jwk.FromRaw([]byte(`abracadabra`))
   if err != nil {
     fmt.Printf("failed to create key: %s\n", err)
@@ -366,7 +366,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_VerifyWithKey() {
+func Example_jws_verify_with_key() {
   const src = `eyJhbGciOiJIUzI1NiJ9.TG9yZW0gaXBzdW0.EjVtju0uXjSz6QevNgAqN1ESd9aNCP7-tJLifkQ0_C0`
 
   key, err := jwk.FromRaw([]byte(`abracadabra`))
@@ -412,7 +412,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_VerifyWithJWKSet() {
+func Example_jws_verify_with_jwk_set() {
   // Setup payload first...
   privkey, err := rsa.GenerateKey(rand.Reader, 2048)
   if err != nil {
@@ -468,7 +468,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jws"
 )
 
-func ExampleJWS_VerifyDetachedPayload() {
+func Example_jws_verify_detached_payload() {
   serialized := `eyJhbGciOiJIUzI1NiJ9..H14oXKwyvAsl0IbBLjw9tLxNIoYisuIyb_oDV4-30Vk`
   payload := `$.02`
 
@@ -588,7 +588,7 @@ func (s CirclEdDSASignerVerifier) Verify(payload []byte, signature []byte, keyif
   }
 }
 
-func ExampleJWS_CustomSignerVerifier() {
+func Example_jws_custom_signer_verifier() {
   // This example shows how to register external jws.Signer / jws.Verifier for
   // a given algorithm.
   jws.RegisterSigner(jwa.EdDSA, jws.SignerFactoryFn(NewCirclEdDSASigner))

diff --git a/docs/03-jwe.md b/docs/03-jwe.md
@@ -35,7 +35,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwe"
 )
 
-func ExampleJWE_Parse() {
+func Example_jwe_parse() {
   const src = `eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.KrFTaMKVY_iUKYYk905QjbUf_fpBXvXCzIAfbPoPMGViDzxtgz5qnch8waV7wraVDfzpW7JfPOw6Nz_-XRwN3Vbud48bRYFw92GkC0M6kpKFpl_xgZxGN47ggNk9hzgqd7mFCuyufeYdn5c2fPoRZAV4UxvakLozEYcQo-eZaFmoYS4pyoC-IKKRikobW8n__LksMzXc_Vps1axn5kdpxsKQ4k1oayvUrgWX2PMxKn_TcLEKHtCN7qRlJ5hkKbZAXAdd34zGWcFV5gc1tcLs6HFhnebo8GUgItTYWBKSKzF6MyLJNRSUPFVq9q-Jxi1juXIlDrv_7rHVsdokQmBfvA.bK7z7Z3gEzFDgDQvNen0Ww.2hngnAVrmucUpJKLgIzYcg.CHs3ZP7JtG430Dl9YAKLMAl`
 
   msg, err := jwe.Parse([]byte(src))
@@ -68,7 +68,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwe"
 )
 
-func ExampleJWE_ReadFile() {
+func Example_jwe_readfile() {
   const src = `eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.KrFTaMKVY_iUKYYk905QjbUf_fpBXvXCzIAfbPoPMGViDzxtgz5qnch8waV7wraVDfzpW7JfPOw6Nz_-XRwN3Vbud48bRYFw92GkC0M6kpKFpl_xgZxGN47ggNk9hzgqd7mFCuyufeYdn5c2fPoRZAV4UxvakLozEYcQo-eZaFmoYS4pyoC-IKKRikobW8n__LksMzXc_Vps1axn5kdpxsKQ4k1oayvUrgWX2PMxKn_TcLEKHtCN7qRlJ5hkKbZAXAdd34zGWcFV5gc1tcLs6HFhnebo8GUgItTYWBKSKzF6MyLJNRSUPFVq9q-Jxi1juXIlDrv_7rHVsdokQmBfvA.bK7z7Z3gEzFDgDQvNen0Ww.2hngnAVrmucUpJKLgIzYcg.CHs3ZP7JtG430Dl9YAKLMAl`
 
   f, err := os.CreateTemp(``, `jwe_readfile_example-*.jwe`)
@@ -118,7 +118,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwk"
 )
 
-func ExampleJWE_Encrypt() {
+func Example_jwe_encrypt() {
   rawprivkey, err := rsa.GenerateKey(rand.Reader, 2048)
   if err != nil {
     fmt.Printf("failed to create raw private key: %s\n", err)
@@ -176,7 +176,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwk"
 )
 
-func ExampleJWE_EncryptJSON() {
+func Example_jwe_encrypt_json() {
   rawprivkey, err := rsa.GenerateKey(rand.Reader, 2048)
   if err != nil {
     fmt.Printf("failed to create raw private key: %s\n", err)
@@ -211,7 +211,7 @@ func ExampleJWE_EncryptJSON() {
   // Lorem ipsum
 }
 
-func ExampleJWE_EncryptJSONMulti() {
+func Example_jwe_encrypt_json_multi() {
   var privkeys []jwk.Key
   var pubkeys []jwk.Key
 
@@ -289,7 +289,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwe"
 )
 
-func ExampleJWE_SignWithHeaders() {
+func Example_jwe_sign_with_headers() {
   privkey, err := rsa.GenerateKey(rand.Reader, 2048)
   if err != nil {
     fmt.Printf("failed to create private key: %s\n", err)
@@ -350,7 +350,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwe"
 )
 
-func ExampleJWE_VerifyWithKey() {
+func Example_jwe_verify_with_key() {
   const payload = "Lorem ipsum"
   encrypted, err := jwe.Encrypt([]byte(payload), jwe.WithKey(jwa.RSA_OAEP, jwkRSAPublicKey))
   if err != nil {
@@ -396,7 +396,7 @@ import (
   "github.com/lestrrat-go/jwx/v2/jwk"
 )
 
-func ExampleJWE_VerifyWithJWKSet() {
+func Example_jwe_verify_with_jwk_set() {
   privkey, err := rsa.GenerateKey(rand.Reader, 2048)
   if err != nil {
     fmt.Printf("failed to create private key: %s\n", err)