From 14da41cfd8a6d7dea9e11a8c92fb1446ac33b19f Mon Sep 17 00:00:00 2001
From: "Pascal S. de Kloe" <pascal@quies.net>
Date: Sun, 24 Mar 2019 18:25:48 +0100
Subject: [PATCH] Documentation typos + sync.

---
 check.go    |  9 +++------
 jwt.go      | 12 ++++++------
 register.go |  1 -
 web.go      |  2 +-
 4 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/check.go b/check.go
index ac0abaa..ac0baa1 100644
--- a/check.go
+++ b/check.go
@@ -20,8 +20,7 @@ var ErrSigMiss = errors.New("jwt: signature mismatch")
 var errPart = errors.New("jwt: missing base64 part")
 
 // ECDSACheck parses a JWT if, and only if, the signature checks out.
-// Note that this excludes unsecured JWTs [ErrUnsecured]. When the
-// algorithm is not in ECDSAAlgs, then the error is ErrAlgUnk.
+// The return is an AlgError when the algorithm is not in ECDSAAlgs.
 // See Valid to complete the verification.
 func ECDSACheck(token []byte, key *ecdsa.PublicKey) (*Claims, error) {
 	firstDot, lastDot, sig, header, err := scan(token)
@@ -46,8 +45,7 @@ func ECDSACheck(token []byte, key *ecdsa.PublicKey) (*Claims, error) {
 }
 
 // HMACCheck parses a JWT if, and only if, the signature checks out.
-// Note that this excludes unsecured JWTs [ErrUnsecured]. When the
-// algorithm is not in HMACAlgs, then the error is ErrAlgUnk.
+// The return is an AlgError when the algorithm is not in HMACAlgs.
 // See Valid to complete the verification.
 func HMACCheck(token, secret []byte) (*Claims, error) {
 	firstDot, lastDot, sig, header, err := scan(token)
@@ -70,8 +68,7 @@ func HMACCheck(token, secret []byte) (*Claims, error) {
 }
 
 // RSACheck parses a JWT if, and only if, the signature checks out.
-// Note that this excludes unsecured JWTs [ErrUnsecured]. When the
-// algorithm is not in RSAAlgs, then the error is ErrAlgUnk.
+// The return is an AlgError when the algorithm is not in RSAAlgs.
 // See Valid to complete the verification.
 func RSACheck(token []byte, key *rsa.PublicKey) (*Claims, error) {
 	firstDot, lastDot, sig, header, err := scan(token)
diff --git a/jwt.go b/jwt.go
index 01b3444..9493f2e 100644
--- a/jwt.go
+++ b/jwt.go
@@ -98,14 +98,11 @@ type Registered struct {
 	ID string `json:"jti,omitempty"`
 }
 
-// Claims is JWT payload representation.
+// Claims is the payload representation.
 type Claims struct {
 	// Registered field values take precedence.
 	Registered
 
-	// Raw encoding as is within the token. This field is read-only.
-	Raw json.RawMessage
-
 	// Set has the claims set mapped by name for non-standard usecases.
 	// Use Registered fields where possible. The Sign methods copy each
 	// non-zero Registered field into this map when not nil. JavaScript
@@ -121,6 +118,9 @@ type Claims struct {
 	//
 	Set map[string]interface{}
 
+	// Raw encoding as is within the token. This field is read-only.
+	Raw json.RawMessage
+
 	// “The "kid" (key ID) Header Parameter is a hint indicating which key
 	// was used to secure the JWS.  This parameter allows originators to
 	// explicitly signal a change of key to recipients.  The structure of
@@ -254,7 +254,7 @@ func (e AlgError) Error() string {
 	return "jwt: algorithm " + strconv.Quote(string(e)) + " not in use"
 }
 
-// NumericTime, named NumericDate, is “A JSON numeric value representing
+// NumericTime implements NumericDate: “A JSON numeric value representing
 // the number of seconds from 1970-01-01T00:00:00Z UTC until the specified
 // UTC date/time, ignoring leap seconds.”
 type NumericTime float64
@@ -277,7 +277,7 @@ func (n *NumericTime) Time() time.Time {
 	return time.Unix(0, int64(float64(*n)*float64(time.Second))).UTC()
 }
 
-// String returns the ISO representation with the empty string for nil.
+// String returns the ISO representation or the empty string for nil.
 func (n *NumericTime) String() string {
 	if n == nil {
 		return ""
diff --git a/register.go b/register.go
index d578119..22ca75c 100644
--- a/register.go
+++ b/register.go
@@ -25,7 +25,6 @@ type KeyRegister struct {
 }
 
 // Check parses a JWT if, and only if, the signature checks out.
-// Note that this excludes unsecured JWTs [ErrUnsecured].
 // See Claims.Valid to complete the verification.
 func (keys *KeyRegister) Check(token []byte) (*Claims, error) {
 	firstDot, lastDot, sig, header, err := scan(token)
diff --git a/web.go b/web.go
index 7640427..232905b 100644
--- a/web.go
+++ b/web.go
@@ -107,7 +107,7 @@ func (c *Claims) RSASignHeader(r *http.Request, alg string, key *rsa.PrivateKey)
 }
 
 // Handler protects an http.Handler with security enforcements.
-// Requests are passed to Target only when the JWT checks out.
+// Requests are only passed to Target if the JWT checks out.
 type Handler struct {
 	// Target is the secured service.
 	Target http.Handler