Improve internal function docs

internal/auth.go

@@ -17,6 +17,7 @@ import (
 
 // Request Validation
 
+// ValidateCookie verifies that a cookie matches the expected format of:
 // Cookie = hash(secret, cookie domain, email, expires)|expires|email
 func ValidateCookie(r *http.Request, c *http.Cookie) (string, error) {
 	parts := strings.Split(c.Value, "|")
@@ -55,7 +56,7 @@ func ValidateCookie(r *http.Request, c *http.Cookie) (string, error) {
 	return parts[2], nil
 }
 
-// Validate email
+// ValidateEmail verifies that an email is permitted by the current config
 func ValidateEmail(email string) bool {
 	found := false
 	if len(config.Whitelist) > 0 {
@@ -126,7 +127,7 @@ func useAuthDomain(r *http.Request) (bool, string) {
 
 // Cookie methods
 
-// Create an auth cookie
+// MakeCookie creates an auth cookie
 func MakeCookie(r *http.Request, email string) *http.Cookie {
 	expires := cookieExpiry()
 	mac := cookieSignature(r, email, fmt.Sprintf("%d", expires.Unix()))
@@ -143,7 +144,7 @@ func MakeCookie(r *http.Request, email string) *http.Cookie {
 	}
 }
 
-// Make a CSRF cookie (used during login only)
+// MakeCSRFCookie makes a csrf cookie (used during login only)
 func MakeCSRFCookie(r *http.Request, nonce string) *http.Cookie {
 	return &http.Cookie{
 		Name:     config.CSRFCookieName,
@@ -156,7 +157,7 @@ func MakeCSRFCookie(r *http.Request, nonce string) *http.Cookie {
 	}
 }
 
-// Create a cookie to clear csrf cookie
+// ClearCSRFCookie makes an expired csrf cookie to clear csrf cookie
 func ClearCSRFCookie(r *http.Request) *http.Cookie {
 	return &http.Cookie{
 		Name:     config.CSRFCookieName,
@@ -169,7 +170,7 @@ func ClearCSRFCookie(r *http.Request) *http.Cookie {
 	}
 }
 
-// Validate the csrf cookie against state
+// ValidateCSRFCookie validates the csrf cookie against state
 func ValidateCSRFCookie(r *http.Request, c *http.Cookie) (valid bool, provider string, redirect string, err error) {
 	state := r.URL.Query().Get("state")
 
@@ -197,12 +198,13 @@ func ValidateCSRFCookie(r *http.Request, c *http.Cookie) (valid bool, provider s
 	return true, params[:split], params[split+1:], nil
 }
 
+// MakeState generates a state value
 func MakeState(r *http.Request, p provider.Provider, nonce string) string {
 	return fmt.Sprintf("%s:%s:%s", nonce, p.Name(), returnUrl(r))
 }
 
+// Nonce generates a random nonce
 func Nonce() (error, string) {
-	// Make nonce
 	nonce := make([]byte, 16)
 	_, err := rand.Read(nonce)
 	if err != nil {
@@ -263,9 +265,7 @@ func cookieExpiry() time.Time {
 	return time.Now().Local().Add(config.Lifetime)
 }
 
-// Cookie Domain
-
-// Cookie Domain
+// CookieDomain holds cookie domain info
 type CookieDomain struct {
 	Domain       string
 	DomainLen    int
@@ -273,6 +273,7 @@ type CookieDomain struct {
 	SubDomainLen int
 }
 
+// NewCookieDomain creates a new CookieDomain from the given domain string
 func NewCookieDomain(domain string) *CookieDomain {
 	return &CookieDomain{
 		Domain:       domain,
@@ -282,6 +283,7 @@ func NewCookieDomain(domain string) *CookieDomain {
 	}
 }
 
+// Match checks if the given host matches this CookieDomain
 func (c *CookieDomain) Match(host string) bool {
 	// Exact domain match?
 	if host == c.Domain {
@@ -296,19 +298,22 @@ func (c *CookieDomain) Match(host string) bool {
 	return false
 }
 
+// UnmarshalFlag converts a string to a CookieDomain
 func (c *CookieDomain) UnmarshalFlag(value string) error {
 	*c = *NewCookieDomain(value)
 	return nil
 }
 
+// MarshalFlag converts a CookieDomain to a string
 func (c *CookieDomain) MarshalFlag() (string, error) {
 	return c.Domain, nil
 }
 
-// Legacy support for comma separated list of cookie domains
-
+// CookieDomains provides legacy sypport for comma separated list of cookie domains
 type CookieDomains []CookieDomain
 
+// UnmarshalFlag converts a comma separated list of cookie domains to an array
+// of CookieDomains
 func (c *CookieDomains) UnmarshalFlag(value string) error {
 	if len(value) > 0 {
 		for _, d := range strings.Split(value, ",") {
@@ -319,6 +324,7 @@ func (c *CookieDomains) UnmarshalFlag(value string) error {
 	return nil
 }
 
+// MarshalFlag converts an array of CookieDomain to a comma seperated list
 func (c *CookieDomains) MarshalFlag() (string, error) {
 	var domains []string
 	for _, d := range *c {