From 3ae2a4a3c8b8e42a0d9c896dd60f05c1c4e6437c Mon Sep 17 00:00:00 2001
From: Christian Banse <oxisto@aybaze.com>
Date: Fri, 15 Sep 2023 22:33:21 +0200
Subject: [PATCH] Added more Godoc

---
 encoder.go       |  2 ++
 parser_option.go | 54 ++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/encoder.go b/encoder.go
index 5f21e80..1a98906 100644
--- a/encoder.go
+++ b/encoder.go
@@ -2,6 +2,8 @@ package jwt
 
 import "io"
 
+// Base64Encoding represents an object that can encode and decode base64. A
+// common example is [encoding/base64.Encoding].
 type Base64Encoding interface {
 	EncodeToString(src []byte) string
 	DecodeString(s string) ([]byte, error)
diff --git a/parser_option.go b/parser_option.go
index 8d701a0..9513387 100644
--- a/parser_option.go
+++ b/parser_option.go
@@ -124,25 +124,67 @@ func WithPaddingAllowed() ParserOption {
 // WithStrictDecoding will switch the codec used for decoding JWTs into strict
 // mode. In this mode, the decoder requires that trailing padding bits are zero,
 // as described in RFC 4648 section 3.5.
+//
+// Note: This is only supported when using [encoding/base64.Encoding], but not
+// by any other decoder specified with [WithBase64Decoder].
 func WithStrictDecoding() ParserOption {
 	return func(p *Parser) {
 		p.decodeStrict = true
 	}
 }
 
-// WithJSONDecoder supports a custom [JSONUnmarshal] to use in parsing the JWT.
-func WithJSONDecoder[T JSONDecoder](f JSONUnmarshalFunc, f2 JSONNewDecoderFunc[T]) ParserOption {
+// WithJSONDecoder supports a custom JSON decoder to use in parsing the JWT.
+// There are two functions that can be supplied:
+//   - jsonUnmarshal is a [JSONUnmarshalFunc] that is used for the
+//     un-marshalling the header and claims when no other options are specified
+//   - jsonNewDecoder is a [JSONNewDecoderFunc] that is used to create an object
+//     satisfying the [JSONDecoder] interface.
+//
+// The latter is used when the [WithJSONNumber] option is used.
+//
+// If any of the supplied functions is set to nil, the defaults from the Go
+// standard library, [encoding/json.Unmarshal] and [encoding/json.NewDecoder]
+// are used.
+//
+// Example using the https://github.com/bytedance/sonic library.
+//
+//	import (
+//		"github.com/bytedance/sonic"
+//	)
+//
+//	var parser = NewParser(WithJSONDecoder(sonic.Unmarshal, sonic.ConfigDefault.NewDecoder))
+func WithJSONDecoder[T JSONDecoder](jsonUnmarshal JSONUnmarshalFunc, jsonNewDecoder JSONNewDecoderFunc[T]) ParserOption {
 	return func(p *Parser) {
-		p.jsonUnmarshal = f
+		p.jsonUnmarshal = jsonUnmarshal
 		// This seems to be necessary, since we don't want to store the specific
-		// JSONDecoder type in our parser, but need it in the function interface.
+		// JSONDecoder type in our parser, but need it in the function
+		// interface.
 		p.jsonNewDecoder = func(r io.Reader) JSONDecoder {
-			return f2(r)
+			return jsonNewDecoder(r)
 		}
 	}
 }
 
-// WithBase64Decoder supports a custom [Base64Encoding] to use in parsing the JWT.
+// WithBase64Decoder supports a custom Base64 when decoding a base64 encoded
+// token. Two encoding can be specified:
+//   - rawURL needs to contain a [Base64Encoding] that is based on base64url
+//     without padding. This is used for parsing tokens with the default
+//     options.
+//   - url needs to contain a [Base64Encoding] based on base64url with padding.
+//     The sole use of this to decode tokens when [WithPaddingAllowed] is
+//     enabled.
+//
+// If any of the supplied encodings are set to nil, the defaults from the Go
+// standard library, [encoding/base64.RawURLEncoding] and
+// [encoding/base64.URLEncoding] are used.
+//
+// Example using the https://github.com/segmentio/asm library.
+//
+//	import (
+//		asmbase64 "github.com/segmentio/asm/base64"
+//	)
+//
+//	var parser = NewParser(WithBase64Decoder(asmbase64.RawURLEncoding, asmbase64.URLEncoding))
 func WithBase64Decoder(rawURL Base64Encoding, url Base64Encoding) ParserOption {
 	return func(p *Parser) {
 		p.rawUrlBase64Encoding = rawURL