docs: package-wide comment sweep (non-security)

paskal · umputun · commit 441f45a5de07 · 2026-05-20T22:12:11.000-05:00
Pre-existing comment drift in files unrelated to the recent security fix — unrelated docstrings that misled, said the wrong thing, or were copy-paste leftovers. Mirrored across v1 and v2. The security-fix docstring fixes (avatar/avatar.go security comments and auth.go withSecurityHeaders) live in PR #291 and are intentionally NOT included here so the two PRs stay independent. Findings: * avatar/gridfs.go — ID doc claimed MD5 sourced from gridfs; metadata.hash is the sha1 written at Put time. * avatar/bolt.go, avatar/gridfs.go — Put docs and BoltDB type doc claimed these layers "resize" the image; they only copy bytes. Resize happens in Proxy.resize upstream. * avatar/store.go — Migrate doc didn't mention that per-avatar Get/Put/Close errors are logged and skipped, and that the returned count is "ids attempted", not "ids stored". * provider/oauth1.go — initOauth1Handler doc and DEBUG log both said "oauth2". * provider/service.go — Service.Handler doc said "returns auth routes"; it dispatches login/callback/logout. * provider/telegram.go — processUpdates claimed to return an offset (no return value); checkToken doc described an "address or empty string" return shape but the signature is (*token.User, error). * provider/verify.go — Sender interface doc locked the contract to "send emails", contradicting the broader "email, IM, or anything else" on VerifyHandler. AuthHandler comment was copy-pasted from direct. * provider/dev_provider.go — NewDev doc said "for admin user"; just makes the dev oauth2 provider. * middleware/user_updater.go — UserUpdFunc adapter doc said result "is a Handler"; implements UserUpdater. * logger/interface.go — Func adapter doc said "Logf calls f(id)"; actually calls f(format, args...). * token/jwt.go — SendJWTHeader option doc said "instead of cookie"; Set sends header AND cookie. Set doc referenced a "permanent flag" that doesn't exist in the signature (controlled by claims.SessionOnly/Handshake). Get doc oversimplified the XSRF gate. Update/Validate adapter docs said "calls f(id)"; actually f(claims) and f(token, claims). * token/user.go — HashID inline "or empty" was wrong; an empty val never matches reValidSha. * auth.go — BasicAuthChecker doc grammar broken and understated behavior (AdminPasswd is bypassed entirely, not "ignored"); "peak dev provider" typo; AvatarProxy doc was a sentence fragment. All changes mirrored across v1 and v2. Build green, lint clean, go fix clean.
diff --git a/auth.go b/auth.go
@@ -58,7 +58,7 @@ type Opts struct {
 	XSRFHeaderKey     string        // default "X-XSRF-TOKEN"
 	XSRFIgnoreMethods []string      // disable XSRF protection for the specified request methods (ex. []string{"GET", "POST")}, default empty
 	JWTQuery          string        // default "token"
-	SendJWTHeader     bool          // if enabled send JWT as a header instead of cookie
+	SendJWTHeader     bool          // if enabled, also send JWT as a response header (in addition to the cookie)
 	SameSiteCookie    http.SameSite // limit cross-origin requests with SameSite cookie attribute
 
 	Issuer string // optional value for iss claim, usually the application name, default "go-pkgz/auth"
@@ -81,7 +81,7 @@ type Opts struct {
 	UseGravatar       bool         // for email based auth (verified provider) use gravatar service
 
 	AdminPasswd      string                   // if presented, allows basic auth with user admin and given password
-	BasicAuthChecker middleware.BasicAuthFunc // user custom checker for basic auth, if one defined then "AdminPasswd" will ignored
+	BasicAuthChecker middleware.BasicAuthFunc // custom checker for basic auth; when set, AdminPasswd is bypassed entirely
 	AudienceReader   token.Audience           // list of allowed aud values, default (empty) allows any
 	AudSecrets       bool                     // allow multiple secrets (secret per aud)
 	Logger           logger.L                 // logger interface, default is no logging at all
@@ -503,7 +503,7 @@ func (s *Service) AddCustomHandler(p provider.Provider) {
 
 // DevAuth makes dev oauth2 server, for testing and development only!
 func (s *Service) DevAuth() (*provider.DevAuthServer, error) {
-	p, err := s.Provider("dev") // peak dev provider
+	p, err := s.Provider("dev") // peek dev provider
 	if err != nil {
 		return nil, fmt.Errorf("dev provider not registered: %w", err)
 	}
@@ -531,7 +531,7 @@ func (s *Service) TokenService() *token.Service {
 	return s.jwtService
 }
 
-// AvatarProxy returns stored in service
+// AvatarProxy returns the avatar.Proxy configured on the service, or nil if no AvatarStore was set.
 func (s *Service) AvatarProxy() *avatar.Proxy {
 	return s.avatarProxy
 }
diff --git a/avatar/bolt.go b/avatar/bolt.go
@@ -11,7 +11,7 @@ import (
 
 // BoltDB implements avatar store with bolt
 // using separate db (file) with "avatars" bucket to keep image bin and "metas" bucket
-// to keep sha1 of picture. avatarID (base file name) used as a key for both.
+// to keep a sha1 fingerprint of the stored bytes. avatarID (base file name) used as a key for both.
 type BoltDB struct {
 	fileName string // full path to boltdb
 	db       *bolt.DB
@@ -41,7 +41,9 @@ func NewBoltDB(fileName string, options bolt.Options) (*BoltDB, error) {
 	return &BoltDB{db: db, fileName: fileName}, nil
 }
 
-// Put avatar to bolt, key by avatarID. Trying to resize image and lso calculates sha1 of the file for ID func
+// Put stores avatar bytes read from reader in the "avatars" bucket and a sha1 of the
+// same bytes in the "metas" bucket, both keyed by the encoded userID with .image suffix.
+// Resizing happens upstream in Proxy.resize; this layer only writes what it is given.
 func (b *BoltDB) Put(userID string, reader io.Reader) (avatar string, err error) {
 	id := encodeID(userID)
 
diff --git a/avatar/gridfs.go b/avatar/gridfs.go
@@ -27,7 +27,9 @@ type GridFS struct {
 	timeout    time.Duration
 }
 
-// Put avatar to gridfs object, try to resize
+// Put stores avatar bytes read from reader in GridFS, keyed by the encoded userID
+// with .image suffix, and records the sha1 of those bytes in the file's metadata.
+// Resizing happens upstream in Proxy.resize; this layer only writes what it is given.
 func (gf *GridFS) Put(userID string, reader io.Reader) (avatar string, err error) {
 	id := encodeID(userID)
 	bucket, err := gridfs.NewBucket(gf.db, &options.BucketOptions{Name: &gf.bucketName})
@@ -59,7 +61,8 @@ func (gf *GridFS) Get(avatar string) (reader io.ReadCloser, size int, err error)
 	return io.NopCloser(buf), int(sz), nil
 }
 
-// ID returns a fingerprint of the avatar content. Uses MD5 because gridfs provides it directly
+// ID returns the sha1 fingerprint of the avatar content stored in the GridFS file's
+// metadata at Put time, or an encoded fallback id when the file lookup/decode fails.
 func (gf *GridFS) ID(avatar string) (id string) {
 
 	finfo := struct {
diff --git a/avatar/store.go b/avatar/store.go
@@ -70,7 +70,10 @@ func NewStore(uri string) (Store, error) {
 	return nil, fmt.Errorf("can't parse store url %s", uri)
 }
 
-// Migrate avatars between stores
+// Migrate copies avatars from src to dst, returning the number of ids enumerated
+// from src and the first List error if any. Per-avatar Get/Put/Close failures are
+// logged with [WARN] and skipped — they do not abort the migration or surface in
+// the returned error, so the returned count is "ids attempted", not "ids stored".
 func Migrate(dst, src Store) (int, error) {
 	ids, err := src.List()
 	if err != nil {
diff --git a/logger/interface.go b/logger/interface.go
@@ -12,7 +12,7 @@ type L interface {
 // Func type is an adapter to allow the use of ordinary functions as Logger.
 type Func func(format string, args ...any)
 
-// Logf calls f(id)
+// Logf calls f(format, args...).
 func (f Func) Logf(format string, args ...any) { f(format, args...) }
 
 // NoOp logger
diff --git a/middleware/user_updater.go b/middleware/user_updater.go
@@ -12,7 +12,7 @@ type UserUpdater interface {
 }
 
 // UserUpdFunc type is an adapter to allow the use of ordinary functions as UserUpdater. If f is a function
-// with the appropriate signature, UserUpdFunc(f) is a Handler that calls f.
+// with the appropriate signature, UserUpdFunc(f) is a UserUpdater that calls f.
 type UserUpdFunc func(user token.User) token.User
 
 // Update calls f(user)
diff --git a/provider/dev_provider.go b/provider/dev_provider.go
@@ -167,7 +167,7 @@ func (d *DevAuthServer) Shutdown() {
 	d.lock.Unlock()
 }
 
-// NewDev makes dev oauth2 provider for admin user
+// NewDev makes a dev oauth2 provider intended for local development only.
 func NewDev(p Params) Oauth2Handler {
 	if p.Port == 0 {
 		p.Port = defDevAuthPort
diff --git a/provider/oauth1.go b/provider/oauth1.go
@@ -190,7 +190,7 @@ func (h Oauth1Handler) makeRedirURL(path string) string {
 	return strings.TrimSuffix(h.URL, "/") + strings.TrimSuffix(newPath, "/") + urlCallbackSuffix
 }
 
-// initOauth2Handler makes oauth1 handler for given provider
+// initOauth1Handler makes oauth1 handler for given provider
 func initOauth1Handler(p Params, service Oauth1Handler) Oauth1Handler {
 	if p.L == nil {
 		p.L = logger.NoOp
@@ -200,7 +200,7 @@ func initOauth1Handler(p Params, service Oauth1Handler) Oauth1Handler {
 	service.conf.ConsumerKey = p.Cid
 	service.conf.ConsumerSecret = p.Csecret
 
-	p.Logf("[DEBUG] created %s oauth2, id=%s, redir=%s, endpoint=%s",
+	p.Logf("[DEBUG] created %s oauth1, id=%s, redir=%s, endpoint=%s",
 		service.name, service.Cid, service.makeRedirURL("/{route}/"+service.name+"/"), service.conf.Endpoint)
 	return service
 }
diff --git a/provider/service.go b/provider/service.go
@@ -63,7 +63,7 @@ type Provider interface {
 	LogoutHandler(w http.ResponseWriter, r *http.Request)
 }
 
-// Handler returns auth routes for given provider
+// Handler dispatches login, callback, and logout requests to the underlying provider.
 func (p Service) Handler(w http.ResponseWriter, r *http.Request) {
 
 	if r.Method != http.MethodGet && r.Method != http.MethodPost {
diff --git a/provider/telegram.go b/provider/telegram.go
@@ -156,8 +156,8 @@ func (th *TelegramHandler) ProcessUpdate(ctx context.Context, textUpdate string)
 	return nil
 }
 
-// processUpdates processes a batch of updates from telegram servers
-// Returns offset for subsequent calls
+// processUpdates processes a batch of updates from telegram servers. Offset
+// tracking for subsequent polls is handled inside TelegramAPI.GetUpdates.
 func (th *TelegramHandler) processUpdates(ctx context.Context, updates *telegramUpdate) {
 	for _, update := range updates.Result {
 		if update.Message.Chat.Type != "private" {
@@ -229,7 +229,8 @@ func (th *TelegramHandler) addToken(token string, expires time.Time) error {
 	return nil
 }
 
-// checkToken verifies incoming token, returns the user address if it's confirmed and empty string otherwise
+// checkToken returns the confirmed user for a known token, or an error if the
+// request is missing, expired, or has not been verified yet.
 func (th *TelegramHandler) checkToken(token string) (*authtoken.User, error) {
 	th.requests.RLock()
 	authRequest, ok := th.requests.data[token]
diff --git a/provider/verify.go b/provider/verify.go
@@ -161,7 +161,7 @@ func scrubTokenFromRequest(r *http.Request) *http.Request {
 	return rc
 }
 
-// Sender defines interface to send emails
+// Sender defines interface to deliver a verification message (email, IM, or anything else).
 type Sender interface {
 	Send(address, text string) error
 }
@@ -378,7 +378,7 @@ func (e VerifyHandler) sendConfirmation(w http.ResponseWriter, r *http.Request)
 	rest.RenderJSON(w, rest.JSON{"user": user, "address": address})
 }
 
-// AuthHandler doesn't do anything for direct login as it has no callbacks
+// AuthHandler is a no-op for verify login — the flow has no provider callback.
 func (e VerifyHandler) AuthHandler(http.ResponseWriter, *http.Request) {}
 
 // LogoutHandler - GET /logout
diff --git a/token/jwt.go b/token/jwt.go
@@ -80,7 +80,7 @@ type Opts struct {
 	AudienceReader    Audience      // allowed aud values
 	Issuer            string        // optional value for iss claim, usually application name
 	AudSecrets        bool          // uses different secret for differed auds. important: adds pre-parsing of unverified token
-	SendJWTHeader     bool          // if enabled send JWT as a header instead of cookie
+	SendJWTHeader     bool          // if enabled, also send JWT as a response header (in addition to the cookie)
 	SameSite          http.SameSite // define a cookie attribute making it impossible for the browser to send this cookie cross-site
 }
 
@@ -226,9 +226,11 @@ func (j *Service) validate(claims *Claims) error {
 	return cerr
 }
 
-// Set creates token cookie with xsrf cookie and put it to ResponseWriter
-// accepts claims and sets expiration if none defined. permanent flag means long-living cookie,
-// false makes it session only.
+// Set writes the JWT cookie and the XSRF cookie to w, also emitting the JWT as a
+// response header when SendJWTHeader is enabled. Expiration is filled in from
+// j.TokenDuration if claims.ExpiresAt is zero. The cookie is session-only (MaxAge 0)
+// when claims.SessionOnly is true or claims contain a Handshake; otherwise it lasts
+// j.CookieDuration.
 func (j *Service) Set(w http.ResponseWriter, claims Claims) (Claims, error) {
 	if claims.ExpiresAt == 0 {
 		claims.ExpiresAt = time.Now().Add(j.TokenDuration).Unix()
@@ -269,8 +271,10 @@ func (j *Service) Set(w http.ResponseWriter, claims Claims) (Claims, error) {
 	return claims, nil
 }
 
-// Get token from url, header or cookie
-// if cookie used, verify xsrf token to match
+// Get token from url, header or cookie. When a user token is read from a cookie,
+// XSRF protection requires the request header to match the token claim ID (the
+// value Set also writes to the XSRF cookie), unless DisableXSRF is set, the request
+// method is in XSRFIgnoreMethods, or the claims carry no user.
 func (j *Service) Get(r *http.Request) (Claims, string, error) {
 
 	fromCookie := false
@@ -391,7 +395,7 @@ type ClaimsUpdater interface {
 // with the appropriate signature, ClaimsUpdFunc(f) is a Handler that calls f.
 type ClaimsUpdFunc func(claims Claims) Claims
 
-// Update calls f(id)
+// Update calls f(claims).
 func (f ClaimsUpdFunc) Update(claims Claims) Claims {
 	return f(claims)
 }
@@ -406,7 +410,7 @@ type Validator interface {
 // with the appropriate signature, ValidatorFunc(f) is a Validator that calls f.
 type ValidatorFunc func(token string, claims Claims) bool
 
-// Validate calls f(id)
+// Validate calls f(token, claims).
 func (f ValidatorFunc) Validate(token string, claims Claims) bool {
 	return f(token, claims)
 }
diff --git a/token/user.go b/token/user.go
@@ -109,7 +109,7 @@ func (u *User) SetSliceAttr(key string, val []string) {
 func HashID(h hash.Hash, val string) string {
 
 	if reValidSha.MatchString(val) {
-		return val // already hashed or empty
+		return val // already a sha1 hex digest, pass through unchanged
 	}
 
 	if _, err := io.WriteString(h, val); err != nil {
diff --git a/v2/auth.go b/v2/auth.go
@@ -58,7 +58,7 @@ type Opts struct {
 	XSRFHeaderKey     string        // default "X-XSRF-TOKEN"
 	XSRFIgnoreMethods []string      // disable XSRF protection for the specified request methods (ex. []string{"GET", "POST")}, default empty
 	JWTQuery          string        // default "token"
-	SendJWTHeader     bool          // if enabled send JWT as a header instead of cookie
+	SendJWTHeader     bool          // if enabled, also send JWT as a response header (in addition to the cookie)
 	SameSiteCookie    http.SameSite // limit cross-origin requests with SameSite cookie attribute
 
 	Issuer string // optional value for iss claim, usually the application name, default "go-pkgz/auth"
@@ -81,7 +81,7 @@ type Opts struct {
 	UseGravatar       bool         // for email based auth (verified provider) use gravatar service
 
 	AdminPasswd      string                      // if presented, allows basic auth with user admin and given password
-	BasicAuthChecker middleware.BasicAuthFunc    // user custom checker for basic auth, if one defined then "AdminPasswd" will ignored
+	BasicAuthChecker middleware.BasicAuthFunc    // custom checker for basic auth; when set, AdminPasswd is bypassed entirely
 	AudienceReader   token.Audience              // list of allowed aud values, default (empty) allows any
 	AudSecrets       bool                        // allow multiple secrets (secret per aud)
 	Logger           logger.L                    // logger interface, default is no logging at all
@@ -504,7 +504,7 @@ func (s *Service) AddCustomHandler(p provider.Provider) {
 
 // DevAuth makes dev oauth2 server, for testing and development only!
 func (s *Service) DevAuth() (*provider.DevAuthServer, error) {
-	p, err := s.Provider("dev") // peak dev provider
+	p, err := s.Provider("dev") // peek dev provider
 	if err != nil {
 		return nil, fmt.Errorf("dev provider not registered: %w", err)
 	}
@@ -532,7 +532,7 @@ func (s *Service) TokenService() *token.Service {
 	return s.jwtService
 }
 
-// AvatarProxy returns stored in service
+// AvatarProxy returns the avatar.Proxy configured on the service, or nil if no AvatarStore was set.
 func (s *Service) AvatarProxy() *avatar.Proxy {
 	return s.avatarProxy
 }
diff --git a/v2/avatar/bolt.go b/v2/avatar/bolt.go
@@ -11,7 +11,7 @@ import (
 
 // BoltDB implements avatar store with bolt
 // using separate db (file) with "avatars" bucket to keep image bin and "metas" bucket
-// to keep sha1 of picture. avatarID (base file name) used as a key for both.
+// to keep a sha1 fingerprint of the stored bytes. avatarID (base file name) used as a key for both.
 type BoltDB struct {
 	fileName string // full path to boltdb
 	db       *bolt.DB
@@ -41,7 +41,9 @@ func NewBoltDB(fileName string, options bolt.Options) (*BoltDB, error) {
 	return &BoltDB{db: db, fileName: fileName}, nil
 }
 
-// Put avatar to bolt, key by avatarID. Trying to resize image and lso calculates sha1 of the file for ID func
+// Put stores avatar bytes read from reader in the "avatars" bucket and a sha1 of the
+// same bytes in the "metas" bucket, both keyed by the encoded userID with .image suffix.
+// Resizing happens upstream in Proxy.resize; this layer only writes what it is given.
 func (b *BoltDB) Put(userID string, reader io.Reader) (avatar string, err error) {
 	id := encodeID(userID)
 
diff --git a/v2/avatar/gridfs.go b/v2/avatar/gridfs.go
@@ -27,7 +27,9 @@ type GridFS struct {
 	timeout    time.Duration
 }
 
-// Put avatar to gridfs object, try to resize
+// Put stores avatar bytes read from reader in GridFS, keyed by the encoded userID
+// with .image suffix, and records the sha1 of those bytes in the file's metadata.
+// Resizing happens upstream in Proxy.resize; this layer only writes what it is given.
 func (gf *GridFS) Put(userID string, reader io.Reader) (avatar string, err error) {
 	id := encodeID(userID)
 	bucket, err := gridfs.NewBucket(gf.db, &options.BucketOptions{Name: &gf.bucketName})
@@ -59,7 +61,8 @@ func (gf *GridFS) Get(avatar string) (reader io.ReadCloser, size int, err error)
 	return io.NopCloser(buf), int(sz), nil
 }
 
-// ID returns a fingerprint of the avatar content. Uses MD5 because gridfs provides it directly
+// ID returns the sha1 fingerprint of the avatar content stored in the GridFS file's
+// metadata at Put time, or an encoded fallback id when the file lookup/decode fails.
 func (gf *GridFS) ID(avatar string) (id string) {
 
 	finfo := struct {
diff --git a/v2/avatar/store.go b/v2/avatar/store.go
@@ -70,7 +70,10 @@ func NewStore(uri string) (Store, error) {
 	return nil, fmt.Errorf("can't parse store url %s", uri)
 }
 
-// Migrate avatars between stores
+// Migrate copies avatars from src to dst, returning the number of ids enumerated
+// from src and the first List error if any. Per-avatar Get/Put/Close failures are
+// logged with [WARN] and skipped — they do not abort the migration or surface in
+// the returned error, so the returned count is "ids attempted", not "ids stored".
 func Migrate(dst, src Store) (int, error) {
 	ids, err := src.List()
 	if err != nil {
diff --git a/v2/logger/interface.go b/v2/logger/interface.go
@@ -12,7 +12,7 @@ type L interface {
 // Func type is an adapter to allow the use of ordinary functions as Logger.
 type Func func(format string, args ...any)
 
-// Logf calls f(id)
+// Logf calls f(format, args...).
 func (f Func) Logf(format string, args ...any) { f(format, args...) }
 
 // NoOp logger
diff --git a/v2/middleware/user_updater.go b/v2/middleware/user_updater.go
@@ -12,7 +12,7 @@ type UserUpdater interface {
 }
 
 // UserUpdFunc type is an adapter to allow the use of ordinary functions as UserUpdater. If f is a function
-// with the appropriate signature, UserUpdFunc(f) is a Handler that calls f.
+// with the appropriate signature, UserUpdFunc(f) is a UserUpdater that calls f.
 type UserUpdFunc func(user token.User) token.User
 
 // Update calls f(user)
diff --git a/v2/provider/dev_provider.go b/v2/provider/dev_provider.go
@@ -167,7 +167,7 @@ func (d *DevAuthServer) Shutdown() {
 	d.lock.Unlock()
 }
 
-// NewDev makes dev oauth2 provider for admin user
+// NewDev makes a dev oauth2 provider intended for local development only.
 func NewDev(p Params) Oauth2Handler {
 	if p.Port == 0 {
 		p.Port = defDevAuthPort
diff --git a/v2/provider/oauth1.go b/v2/provider/oauth1.go
@@ -190,7 +190,7 @@ func (h Oauth1Handler) makeRedirURL(path string) string {
 	return strings.TrimSuffix(h.URL, "/") + strings.TrimSuffix(newPath, "/") + urlCallbackSuffix
 }
 
-// initOauth2Handler makes oauth1 handler for given provider
+// initOauth1Handler makes oauth1 handler for given provider
 func initOauth1Handler(p Params, service Oauth1Handler) Oauth1Handler {
 	if p.L == nil {
 		p.L = logger.NoOp
@@ -200,7 +200,7 @@ func initOauth1Handler(p Params, service Oauth1Handler) Oauth1Handler {
 	service.conf.ConsumerKey = p.Cid
 	service.conf.ConsumerSecret = p.Csecret
 
-	p.Logf("[DEBUG] created %s oauth2, id=%s, redir=%s, endpoint=%s",
+	p.Logf("[DEBUG] created %s oauth1, id=%s, redir=%s, endpoint=%s",
 		service.name, service.Cid, service.makeRedirURL("/{route}/"+service.name+"/"), service.conf.Endpoint)
 	return service
 }
diff --git a/v2/provider/service.go b/v2/provider/service.go
@@ -63,7 +63,7 @@ type Provider interface {
 	LogoutHandler(w http.ResponseWriter, r *http.Request)
 }
 
-// Handler returns auth routes for given provider
+// Handler dispatches login, callback, and logout requests to the underlying provider.
 func (p Service) Handler(w http.ResponseWriter, r *http.Request) {
 
 	if r.Method != http.MethodGet && r.Method != http.MethodPost {
diff --git a/v2/provider/telegram.go b/v2/provider/telegram.go
diff --git a/v2/provider/verify.go b/v2/provider/verify.go
diff --git a/v2/token/jwt.go b/v2/token/jwt.go
diff --git a/v2/token/user.go b/v2/token/user.go

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ type UserUpdater interface {`
`12`	`12`	`}`
`13`	`13`
`14`	`14`	`// UserUpdFunc type is an adapter to allow the use of ordinary functions as UserUpdater. If f is a function`
`15`		`-// with the appropriate signature, UserUpdFunc(f) is a Handler that calls f.`
	`15`	`+// with the appropriate signature, UserUpdFunc(f) is a UserUpdater that calls f.`
`16`	`16`	`type UserUpdFunc func(user token.User) token.User`
`17`	`17`
`18`	`18`	`// Update calls f(user)`
Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,7 @@ func (d *DevAuthServer) Shutdown() {`
`167`	`167`	`d.lock.Unlock()`
`168`	`168`	`}`
`169`	`169`
`170`		`-// NewDev makes dev oauth2 provider for admin user`
	`170`	`+// NewDev makes a dev oauth2 provider intended for local development only.`
`171`	`171`	`func NewDev(p Params) Oauth2Handler {`
`172`	`172`	`if p.Port == 0 {`
`173`	`173`	`p.Port = defDevAuthPort`
Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ type Provider interface {`
`63`	`63`	`LogoutHandler(w http.ResponseWriter, r *http.Request)`
`64`	`64`	`}`
`65`	`65`
`66`		`-// Handler returns auth routes for given provider`
	`66`	`+// Handler dispatches login, callback, and logout requests to the underlying provider.`
`67`	`67`	`func (p Service) Handler(w http.ResponseWriter, r *http.Request) {`
`68`	`68`
`69`	`69`	`if r.Method != http.MethodGet && r.Method != http.MethodPost {`