docs(jwt): improve documentation of SigningKey, SigningKeys and KeyFunc

Author: antonindrawan

middleware/jwt.go

@@ -29,15 +29,19 @@ type (
 		// ErrorHandlerWithContext is almost identical to ErrorHandler, but it's passed the current context.
 		ErrorHandlerWithContext JWTErrorHandlerWithContext
 
-		// Signing key to validate token. Used as fallback if KeyFunc is nil or SigningKeys has length 0.
-		// Required. This or SigningKeys or KeyFunc.
+		// Signing key to validate token.
+		// This is one of the three options to provide a token validation key.
+		// The order of precedence is a user-defined KeyFunc, SigningKeys and SigningKey.
+		// Required if neither user-defined KeyFunc nor SigningKeys is provided.
 		SigningKey interface{}
 
-		// Map of signing keys to validate token with kid field usage. Used as fallback if KeyFunc is nil.
-		// Required. This or SigningKey or KeyFunc.
+		// Map of signing keys to validate token with kid field usage.
+		// This is one of the three options to provide a token validation key.
+		// The order of precedence is a user-defined KeyFunc, SigningKeys and SigningKey.
+		// Required if neither user-defined KeyFunc nor SigningKey is provided.
 		SigningKeys map[string]interface{}
 
-		// Signing method, used to check token signing method.
+		// Signing method used to check the token's signing algorithm.
 		// Optional. Default value HS256.
 		SigningMethod string
 
@@ -64,11 +68,15 @@ type (
 		// Optional. Default value "Bearer".
 		AuthScheme string
 
-		// KeyFunc defines a function to supply the key for a token verification.
+		// KeyFunc defines a user-defined function that supplies the public key for a token validation.
+		// The function shall take care of verifying the signing algorithm and selecting the proper key.
+		// A user-defined KeyFunc can be useful if tokens are issued by an external party.
+		//
 		// When a user-defined KeyFunc is provided, SigningKey, SigningKeys, and SigningMethod are ignored.
-		// Required. This or SigningKey or SigningKeys.
+		// This is one of the three options to provide a token validation key.
+		// The order of precedence is a user-defined KeyFunc, SigningKeys and SigningKey.
+		// Required if neither SigningKeys nor SigningKey is provided.
 		// Default to an internal implementation verifying the signing algorithm and selecting the proper key.
-		// See: `jwt.Keyfunc`
 		KeyFunc jwt.Keyfunc
 	}