Add docstrings to many functions

actions.go

@@ -22,7 +22,7 @@ type RequestBase struct {
 
 type userCtxKeyType int
 
-var userCtxKey userCtxKeyType = 0
+var userCtxKey userCtxKeyType
 
 func userFromContext(ctx context.Context) string {
 	s, ok := ctx.Value(userCtxKey).(string)
@@ -34,7 +34,7 @@ func userFromContext(ctx context.Context) string {
 
 type commentCtxKeyType int
 
-var commentCtxKey commentCtxKeyType = 0
+var commentCtxKey commentCtxKeyType
 
 func commentFromContext(ctx context.Context) string {
 	s, ok := ctx.Value(commentCtxKey).(string)
@@ -44,6 +44,7 @@ func commentFromContext(ctx context.Context) string {
 	return ""
 }
 
+// NewContext returns a new Context with some request-related values set.
 func (r RequestBase) NewContext(ctx context.Context) context.Context {
 	ctx = context.WithValue(ctx, userCtxKey, r.Username)
 	if r.Comment != "" {
@@ -68,6 +69,7 @@ type ResourceRequestBase struct {
 	Comment string `json:"comment,omitempty"`
 }
 
+// NewContext returns a new Context with some request-related values set.
 func (r ResourceRequestBase) NewContext(ctx context.Context) context.Context {
 	if u := r.ResourceID.User(); u != "" {
 		ctx = context.WithValue(ctx, userCtxKey, u)
@@ -78,6 +80,7 @@ func (r ResourceRequestBase) NewContext(ctx context.Context) context.Context {
 	return ctx
 }
 
+// GetUserRequest is the request type for AccountService.GetUser().
 type GetUserRequest struct {
 	RequestBase
 }
@@ -99,6 +102,7 @@ func (s *AccountService) setResourceStatus(ctx context.Context, tx TX, r *Resour
 	return nil
 }
 
+// DisableResourceRequest is the request type for AccountService.DisableResource().
 type DisableResourceRequest struct {
 	ResourceRequestBase
 }
@@ -114,6 +118,7 @@ func (s *AccountService) DisableResource(ctx context.Context, tx TX, req *Disabl
 	})
 }
 
+// EnableResourceRequest is the request type for AccountService.EnableResource().
 type EnableResourceRequest struct {
 	ResourceRequestBase
 }
@@ -129,11 +134,13 @@ func (s *AccountService) EnableResource(ctx context.Context, tx TX, req *EnableR
 	})
 }
 
+// ChangeUserPasswordRequest is the request type for AccountService.ChangeUserPassword().
 type ChangeUserPasswordRequest struct {
 	PrivilegedRequestBase
 	Password string `json:"password"`
 }
 
+// Vaildate the request.
 func (r *ChangeUserPasswordRequest) Validate(ctx context.Context, s *AccountService) error {
 	return s.passwordValidator(ctx, r.Password)
 }
@@ -248,12 +255,15 @@ func reEncryptUserKeys(keys []*UserEncryptionKey, curPassword, newPassword, keyI
 	return keysOut, nil
 }
 
+// CreateApplicationSpecificPasswordRequest is the request type for
+// AccountService.CreateApplicationSpecificPassword().
 type CreateApplicationSpecificPasswordRequest struct {
 	PrivilegedRequestBase
 	Service string `json:"service"`
 	Comment string `json:"comment"`
 }
 
+// Validate the request.
 func (r *CreateApplicationSpecificPasswordRequest) Validate(_ context.Context, _ *AccountService) error {
 	if r.Service == "" {
 		return errors.New("empty 'service' attribute")
@@ -261,6 +271,8 @@ func (r *CreateApplicationSpecificPasswordRequest) Validate(_ context.Context, _
 	return nil
 }
 
+// CreateApplicationSpecificPasswordResponse is the response type for
+// AccountService.CreateApplicationSpecificPassword().
 type CreateApplicationSpecificPasswordResponse struct {
 	Password string `json:"password"`
 }
@@ -310,6 +322,8 @@ func (s *AccountService) CreateApplicationSpecificPassword(ctx context.Context,
 	return &resp, err
 }
 
+// DeleteApplicationSpecificPasswordRequest is the request type for
+// AccountService.DeleteApplicationSpecificPassword().
 type DeleteApplicationSpecificPasswordRequest struct {
 	RequestBase
 	AspID string `json:"asp_id"`
@@ -348,12 +362,14 @@ func (s *AccountService) DeleteApplicationSpecificPassword(ctx context.Context,
 	})
 }
 
+// MoveResourceRequest is the request type for AccountService.MoveResource().
 type MoveResourceRequest struct {
 	RequestBase
 	ResourceID ResourceID `json:"resource_id"`
 	Shard      string     `json:"shard"`
 }
 
+// MoveResourceResponse is the response type for AccountService.MoveResource().
 type MoveResourceResponse struct {
 	MovedIDs []string `json:"moved_ids"`
 }
@@ -395,11 +411,13 @@ func (s *AccountService) MoveResource(ctx context.Context, tx TX, req *MoveResou
 	return &resp, err
 }
 
+// EnableOTPRequest is the request type for AccountService.EnableOTP().
 type EnableOTPRequest struct {
 	RequestBase
 	TOTPSecret string `json:"totp_secret"`
 }
 
+// Validate the request.
 func (r *EnableOTPRequest) Validate(_ context.Context, _ *AccountService) error {
 	// TODO: the length here is bogus, replace with real value.
 	if r.TOTPSecret != "" && len(r.TOTPSecret) != 32 {
@@ -408,6 +426,7 @@ func (r *EnableOTPRequest) Validate(_ context.Context, _ *AccountService) error
 	return nil
 }
 
+// EnableOTPResponse is the response type for AccountService.EnableOTP().
 type EnableOTPResponse struct {
 	TOTPSecret string `json:"totp_secret"`
 }
@@ -443,6 +462,7 @@ func (s *AccountService) EnableOTP(ctx context.Context, tx TX, req *EnableOTPReq
 	return &resp, err
 }
 
+// DisableOTPRequest is the request type for AccountService.DisableOTP().
 type DisableOTPRequest struct {
 	RequestBase
 }

config.go

@@ -6,6 +6,7 @@ import (
 	"git.autistici.org/id/go-sso"
 )
 
+// Config holds the configuration for the AccountService.
 type Config struct {
 	ForbiddenUsernames []string            `yaml:"forbidden_usernames"`
 	AvailableDomains   map[string][]string `yaml:"available_domains"`

errors.go

 package accountserver
 
+import "errors"
+
+var (
+	// ErrUnauthorized means that the request failed due to lack of authorization.
+	ErrUnauthorized = errors.New("unauthorized")
+
+	// ErrUserNotFound is returned when a user object is not found.
+	ErrUserNotFound = errors.New("user not found")
+
+	// ErrResourceNotFound is returned when a resource object is not found.
+	ErrResourceNotFound = errors.New("resource not found")
+)
+
 // It is important to distinguish between different classes of errors,
 // so that they can be translated into distinct HTTP status codes and
 // transmitted back to the client. Since we also want to retain the
@@ -14,6 +27,8 @@ func newAuthError(err error) error {
 	return &authError{err}
 }
 
+// IsAuthError returns true if err is an authentication /
+// authorization error.
 func IsAuthError(err error) bool {
 	_, ok := err.(*authError)
 	return ok
@@ -27,6 +42,8 @@ func newRequestError(err error) error {
 	return &requestError{err}
 }
 
+// IsRequestError returns true if err is a request error (bad
+// request).
 func IsRequestError(err error) bool {
 	_, ok := err.(*requestError)
 	return ok
@@ -40,6 +57,7 @@ func newBackendError(err error) error {
 	return &backendError{err}
 }
 
+// IsBackendError returns true if err is a backend error.
 func IsBackendError(err error) bool {
 	_, ok := err.(*backendError)
 	return ok

service.go

@@ -3,7 +3,6 @@ package accountserver
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"log"
 	"reflect"
 
@@ -68,11 +67,12 @@ type AccountService struct {
 	ssoGroups     []string
 	ssoAdminGroup string
 
-	passwordValidator   ValidatorFunc
-	dataValidators      map[string]ValidatorFunc
-	adminDataValidators map[string]ValidatorFunc
+	passwordValidator ValidatorFunc
+	dataValidators    map[string]ValidatorFunc
+	//adminDataValidators map[string]ValidatorFunc
 }
 
+// NewAccountService builds a new AccountService with the specified configuration.
 func NewAccountService(backend Backend, config *Config) (*AccountService, error) {
 	ssoValidator, err := config.ssoValidator()
 	if err != nil {
@@ -110,12 +110,6 @@ func (s *AccountService) isAdmin(tkt *sso.Ticket) bool {
 	return false
 }
 
-var (
-	ErrUnauthorized     = errors.New("unauthorized")
-	ErrUserNotFound     = errors.New("user not found")
-	ErrResourceNotFound = errors.New("resource not found")
-)
-
 func (s *AccountService) validateSSO(ssoToken string) (*sso.Ticket, error) {
 	return s.validator.Validate(ssoToken, "", s.ssoService, s.ssoGroups)
 }
@@ -144,7 +138,7 @@ func (s *AccountService) getResource(ctx context.Context, tx TX, id ResourceID)
 
 type authUserCtxKeyType int
 
-var authUserCtxKey authUserCtxKeyType = 0
+var authUserCtxKey authUserCtxKeyType
 
 func authUserFromContext(ctx context.Context) string {
 	s, ok := ctx.Value(userCtxKey).(string)

types.go

@@ -34,6 +34,7 @@ type User struct {
 	Resources []*Resource `json:"resources,omitempty"`
 }
 
+// GetResourcesByType returns all resources with the specified type.
 func (u *User) GetResourcesByType(resourceType string) []*Resource {
 	var out []*Resource
 	for _, r := range u.Resources {
@@ -44,6 +45,8 @@ func (u *User) GetResourcesByType(resourceType string) []*Resource {
 	return out
 }
 
+// GetSingleResourceByType returns a single resource of the specified
+// type. If there are none, returns nil.
 func (u *User) GetSingleResourceByType(resourceType string) *Resource {
 	for _, r := range u.Resources {
 		if r.ID.Type() == resourceType {
@@ -53,6 +56,7 @@ func (u *User) GetSingleResourceByType(resourceType string) *Resource {
 	return nil
 }
 
+// GetResourcesByGroup returns all resources belonging to the specified group.
 func (u *User) GetResourcesByGroup(group string) []*Resource {
 	var out []*Resource
 	for _, r := range u.Resources {
@@ -97,18 +101,20 @@ const (
 	ResourceStatusInactive = "inactive"
 )
 
-// Resource ID. This is a a unique primary key in the resources space,
-// with a path-like representation. It must make sense to the database
+// ResourceID is a a unique primary key in the resources space, with a
+// path-like representation. It must make sense to the database
 // backend and be reversible (i.e. there must be a bidirectional
 // mapping between database objects and resource IDs).
 type ResourceID struct {
 	Parts []string
 }
 
+// NewResourceID builds a ResourceID out of a list of path components.
 func NewResourceID(p ...string) ResourceID {
 	return ResourceID{Parts: p}
 }
 
+// Empty returns true if the ResourceID has the nil value.
 func (i ResourceID) Empty() bool {
 	return len(i.Parts) == 0
 }
@@ -151,10 +157,12 @@ func (i ResourceID) String() string {
 	return filepath.Join(tmp...)
 }
 
+// MarshalJSON serializes a resource ID to JSON.
 func (i ResourceID) MarshalJSON() ([]byte, error) {
 	return json.Marshal(i.String())
 }
 
+// UnmarshalJSON deserializes a resource ID from JSON.
 func (i *ResourceID) UnmarshalJSON(data []byte) error {
 	var s string
 	err := json.Unmarshal(data, &s)
@@ -167,6 +175,7 @@ func (i *ResourceID) UnmarshalJSON(data []byte) error {
 	return err
 }
 
+// ParseResourceID parses a string representation of a ResourceID.
 func ParseResourceID(s string) (ResourceID, error) {
 	var id ResourceID
 	for _, e := range strings.Split(s, "/") {