From 2ed3fe8dedd54e07ad8db31bd6f2aba98e2b8c31 Mon Sep 17 00:00:00 2001
From: Dave Grijalva <grijalva@gmail.com>
Date: Fri, 6 Jul 2012 16:12:33 -0700
Subject: [PATCH] documentation

---
 jwt.go            | 10 ++++++++++
 signing_method.go |  3 +++
 2 files changed, 13 insertions(+)

diff --git a/jwt.go b/jwt.go
index d9621ce..0d490ea 100644
--- a/jwt.go
+++ b/jwt.go
@@ -16,6 +16,7 @@ type Token struct {
 	Method    SigningMethod
 	// This is only populated when you Parse a token
 	Signature string
+	// This is only populated when you Parse/Verify a token
 	Valid     bool
 }
 
@@ -29,6 +30,7 @@ func New(method SigningMethod)*Token {
 	}
 }
 
+// Get the complete, signed token
 func (t *Token) SignedString(key []byte)(string, error) {
 	var sig, sstr string
 	var err error
@@ -41,6 +43,10 @@ func (t *Token) SignedString(key []byte)(string, error) {
 	return strings.Join([]string{sstr, sig}, "."), nil
 }
 
+// Generate the signing string.  This is the
+// most expensive part of the whole deal.  Unless you
+// need this for something special, just go straight for
+// the SignedString.
 func (t *Token) SigningString()(string, error) {
 	var err error
 	parts := make([]string, 2)
@@ -121,6 +127,8 @@ func Parse(tokenString string, keyFunc func(*Token) ([]byte, error)) (token *Tok
 	return
 }
 
+// Try to find the token in an http.Request.
+// Currently, it only looks in the Authorization header
 func ParseFromRequest(req *http.Request, keyFunc func(*Token) ([]byte, error)) (token *Token, err error) {
 
 	// Look for an Authorization header
@@ -135,10 +143,12 @@ func ParseFromRequest(req *http.Request, keyFunc func(*Token) ([]byte, error)) (
 
 }
 
+// Encode JWT specific base64url encoding with padding stripped
 func EncodeSegment(seg []byte)string {
 	return strings.TrimRight(base64.URLEncoding.EncodeToString(seg), "=")
 }
 
+// Decode JWT specific base64url encoding with padding stripped
 func DecodeSegment(seg string) ([]byte, error) {
 	// len % 4
 	switch len(seg) % 4 {
diff --git a/signing_method.go b/signing_method.go
index 88e670f..9fead6c 100644
--- a/signing_method.go
+++ b/signing_method.go
@@ -14,10 +14,13 @@ type SigningMethod interface {
 	Alg() string
 }
 
+// Register the "alg" name and a factory function for signing method.
+// This is typically done during init() in the method's implementation
 func RegisterSigningMethod(alg string, f func() SigningMethod) {
 	signingMethods[alg] = f
 }
 
+// Get a signing method from an "alg" string
 func GetSigningMethod(alg string) (method SigningMethod, err error) {
 	if methodF, ok := signingMethods[alg]; ok {
 		method = methodF()