From 4fa34722ef54130257f4fd8962ba573475b8d20d Mon Sep 17 00:00:00 2001
From: serosset <serosset@cisco.com>
Date: Sun, 19 Sep 2021 17:46:37 +0000
Subject: [PATCH] improve code comments, including security consideration

---
 parser.go |  4 ++--
 token.go  | 14 +++++++++-----
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/parser.go b/parser.go
index 0c811f31..bd2fc3ab 100644
--- a/parser.go
+++ b/parser.go
@@ -13,9 +13,9 @@ type Parser struct {
 	SkipClaimsValidation bool     // Skip claims validation during token parsing
 }
 
-// Parse parses, validates, and returns a token.
+// Parse parses, validates, verifies the signature and returns the parsed token.
 // keyFunc will receive the parsed token and should return the key for validating.
-// If everything is kosher, err will be nil
+// If everything is kosher, err will be nil.
 func (p *Parser) Parse(tokenString string, keyFunc Keyfunc) (*Token, error) {
 	return p.ParseWithClaims(tokenString, MapClaims{}, keyFunc)
 }
diff --git a/token.go b/token.go
index b896acb0..e5598922 100644
--- a/token.go
+++ b/token.go
@@ -29,11 +29,12 @@ type Token struct {
 	Valid     bool                   // Is the token valid?  Populated when you Parse/Verify a token
 }
 
-// New creates a new Token.  Takes a signing method
+// New creates a new Token with the specified a signing method and an empty map of claims.
 func New(method SigningMethod) *Token {
 	return NewWithClaims(method, MapClaims{})
 }
 
+// NewWithClaims creates a new Token with the specified signing method and claims.
 func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	return &Token{
 		Header: map[string]interface{}{
@@ -45,7 +46,8 @@ func NewWithClaims(method SigningMethod, claims Claims) *Token {
 	}
 }
 
-// SignedString retrieves the complete, signed token
+// SignedString creates and returns a complete, signed JWT token.
+// The token is signed using the SigningMethod specified in the token.
 func (t *Token) SignedString(key interface{}) (string, error) {
 	var sig, sstr string
 	var err error
@@ -82,9 +84,11 @@ func (t *Token) SigningString() (string, error) {
 	return strings.Join(parts, "."), nil
 }
 
-// Parse parses, validates, and returns a token.
-// keyFunc will receive the parsed token and should return the key for validating.
-// If everything is kosher, err will be nil
+// Parse parses, validates, verifies the signature and returns the parsed token.
+// keyFunc will receive the parsed token and should return the cryptographic key
+// for verifying the signature.
+// keyFunc should validate the 'alg' claim in the token matches the expected algorithm.
+// If everything is kosher, err will be nil.
 func Parse(tokenString string, keyFunc Keyfunc) (*Token, error) {
 	return new(Parser).Parse(tokenString, keyFunc)
 }