fix(*): add docs and other golint fixes

As of these changes, no more golint errors exist

Author: Aaron Schlesinger

pkg/builder.go

@@ -19,7 +19,7 @@ const (
 	StatusLocalError
 )
 
-// Run starts the Builder service.
+// RunBuilder starts the Builder service.
 //
 // The Builder service is responsible for setting up the local container
 // environment and then listening for new builds. The main listening service

pkg/conf/config.go

@@ -11,6 +11,10 @@ const (
 	builderKeyLocation = "/var/run/secrets/api/auth/builder-key"
 )
 
+// EnvConfig is a convenience function to process the envconfig (https://github.com/kelseyhightower/envconfig) based configuration environment variables into conf. Additional notes:
+//
+// - appName will be passed as the first parameter to envconfig.Process
+// - conf should be a pointer to an envconfig compatible struct. If you'd like to use struct tags to customize your struct, see https://github.com/kelseyhightower/envconfig#struct-tag-support
 func EnvConfig(appName string, conf interface{}) error {
 	if err := envconfig.Process(appName, conf); err != nil {
 		return err

pkg/gitreceive/config.go

@@ -10,6 +10,7 @@ const (
 	objectStorageTick = 500
 )
 
+// Config is the envconfig (http://github.com/kelseyhightower/envconfig) compatible struct for the builder's git-receive hook
 type Config struct {
 	// k8s service discovery env vars
 	ControllerHost string `envconfig:"DEIS_CONTROLLER_SERVICE_HOST" required:"true"`
@@ -35,6 +36,7 @@ type Config struct {
 	DockerBuilderImage            string `envconfig:"DOCKERBUILDER_IMAGE_NAME" default:"quay.io/deisci/dockerbuilder:v2-beta"`
 }
 
+// App returns the application name represented by c. The app name is the same as c.Repository with the last '.' and beyond stripped off
 func (c Config) App() string {
 	li := strings.LastIndex(c.Repository, ".")
 	if li == -1 {

pkg/gitreceive/git/sha.go

@@ -12,25 +12,32 @@ const (
 
 var shaRegex = regexp.MustCompile(`^[\da-f]{40}$`)
 
+// ErrInvalidGitSha is returned by NewSha if the given raw sha is invalid for any reason
 type ErrInvalidGitSha struct {
 	sha string
 }
 
+// Error is the error interface implementation
 func (e ErrInvalidGitSha) Error() string {
 	return fmt.Sprintf("git sha %s was invalid", e.sha)
 }
 
+// SHA is the representaton of a git sha
 type SHA struct {
 	full  string
 	short string
 }
 
+// NewSha creates a raw string to a SHA. Returns ErrInvalidGitSha if the sha was invalid
 func NewSha(rawSha string) (*SHA, error) {
 	if !shaRegex.MatchString(rawSha) {
 		return nil, ErrInvalidGitSha{sha: rawSha}
 	}
 	return &SHA{full: rawSha, short: rawSha[0:8]}, nil
 }
 
-func (s SHA) Full() string  { return s.full }
+// Full returns the full git sha
+func (s SHA) Full() string { return s.full }
+
+// Short returns the first 8 characters of the sha
 func (s SHA) Short() string { return s.short }

pkg/gitreceive/run.go

@@ -23,6 +23,7 @@ func readLine(line string) (string, string, string, error) {
 	return spl[0], spl[1], spl[2], nil
 }
 
+// Run runs the git-receive hook
 func Run(conf *Config, fs sys.FS, env sys.Env) error {
 	log.Debug("Running git hook")
 

pkg/gitreceive/storage/client.go

@@ -5,8 +5,10 @@ import (
 	s3 "github.com/minio/minio-go"
 )
 
+// Client is the S3 client combined with the S3 endpoint
 type Client struct {
 	*s3.Client
+	// Endpoint is the the endpoint information for the location that the S3 client will access
 	Endpoint *Endpoint
 }
 

pkg/gitreceive/storage/endpoint.go

@@ -44,9 +44,8 @@ type Endpoint struct {
 func (e *Endpoint) FullURL() string {
 	if e.Secure {
 		return fmt.Sprintf("https://%s", e.URLStr)
-	} else {
-		return fmt.Sprintf("http://%s", e.URLStr)
 	}
+	return fmt.Sprintf("http://%s", e.URLStr)
 }
 
 func getEndpoint(env sys.Env) (*Endpoint, error) {

pkg/gitreceive/storage/interfaces.go

@@ -11,6 +11,7 @@ type BucketCreator interface {
 	MakeBucket(bucketName string, acl s3.BucketACL, location string) error
 }
 
+// FakeMakeBucketCall represents a single call to MakeBucket on a FakeBucketCreator
 type FakeMakeBucketCall struct {
 	BucketName string
 	ACL        s3.BucketACL
@@ -23,7 +24,7 @@ type FakeBucketCreator struct {
 	Calls []FakeMakeBucketCall
 }
 
-// PutObject is the interface definition
+// MakeBucket is the interface definition for BucketCreator
 func (f *FakeBucketCreator) MakeBucket(name string, acl s3.BucketACL, location string) error {
 	f.Calls = append(f.Calls, FakeMakeBucketCall{BucketName: name, ACL: acl, Location: location})
 	return f.Fn(name, acl, location)
@@ -34,6 +35,7 @@ type ObjectStatter interface {
 	StatObject(bucketName, objectKey string) (s3.ObjectInfo, error)
 }
 
+// FakeStatObjectCall represents a single call to StatObject on the FakeObjectStatter
 type FakeStatObjectCall struct {
 	BucketName string
 	ObjectKey  string
@@ -45,7 +47,7 @@ type FakeObjectStatter struct {
 	Calls []FakeStatObjectCall
 }
 
-// PutObject is the interface definition
+// StatObject is the interface definition
 func (f *FakeObjectStatter) StatObject(bucketName, objectKey string) (s3.ObjectInfo, error) {
 	f.Calls = append(f.Calls, FakeStatObjectCall{BucketName: bucketName, ObjectKey: objectKey})
 	return f.Fn(bucketName, objectKey)
@@ -56,6 +58,7 @@ type ObjectPutter interface {
 	PutObject(bucketName, objectKey string, reader io.Reader, contentType string) (int64, error)
 }
 
+// FakePutObjectCall represents a single call to PutObject on a FakeObjectPutter
 type FakePutObjectCall struct {
 	BucketName  string
 	ObjectKey   string
@@ -80,7 +83,7 @@ func (f *FakeObjectPutter) PutObject(bucketName, objectKey string, reader io.Rea
 	return f.Fn(bucketName, objectKey, reader, contentType)
 }
 
-// The s3.Object already satisfies this interface. As long as it has some or all of the functions as s3.Object, it satisfies it. We're making it have all of the functions in this case. You can create a fake object that also has all of these functions.
+// Object is a *(github.com/minio/minio-go).Object compatible interface. Currently, ObjectGetter returns these so that FakeObjectGetters can return mock implementations
 type Object interface {
 	// This is called an interface composition - it automatically gives your interface the function in io.Reader (https://godoc.org/io#Reader) and the function in io.Closer (https://godoc.org/io#Closer)
 	io.ReadCloser
@@ -92,7 +95,7 @@ type Object interface {
 	Stat() (s3.ObjectInfo, error)
 }
 
-// The minio client doesn't already satisfy this interface, because the GetObject func (https://godoc.org/github.com/minio/minio-go#Client.GetObject) doesn't return an Object. Instead, it returns a *s3.Object. We'll create an adapter below
+// ObjectGetter is the interface to get an object from object storage. The minio client doesn't already satisfy this interface, because the GetObject func (https://godoc.org/github.com/minio/minio-go#Client.GetObject) doesn't return an Object. Instead, it returns a *s3.Object. Use the RealObjectGetter below to use the minio client
 type ObjectGetter interface {
 	// GetObject is *almost* the same function as the GetObject func in the minio client, but it returns Object instead of *s3.Object
 	GetObject(string, string) (Object, error)
@@ -103,6 +106,7 @@ type RealObjectGetter struct {
 	Client *s3.Client
 }
 
+// GetObject is the interface implementation for ObjectGetter
 func (r *RealObjectGetter) GetObject(bucket, objKey string) (Object, error) {
 	obj, err := r.Client.GetObject(bucket, objKey)
 	if err != nil {
@@ -113,6 +117,7 @@ func (r *RealObjectGetter) GetObject(bucket, objKey string) (Object, error) {
 	return obj, nil
 }
 
+// FakeGetObjectCall represents a single call a single call to GetObject on a FakeObjectGetter
 type FakeGetObjectCall struct {
 	BucketName string
 	ObjectKey  string

pkg/gitreceive/storage/object.go

@@ -33,13 +33,14 @@ func ObjectExists(statter ObjectStatter, bucketName, objKey string) (bool, error
 	return true, nil
 }
 
+// UploadObject uploads the contents of readaer to ${bucektName}/${objectKey} using the given putter
 func UploadObject(putter ObjectPutter, bucketName, objKey string, reader io.Reader) error {
 	_, err := putter.PutObject(bucketName, objKey, reader, octetStream)
 	return err
 }
 
 // WaitForObject checks statter for the object at ${bucketName}/${objKey} right away, then at every tick, then once when the timeout is up.
-// Returns nil if it finds the object before or at timeout. Otherwise returns an error
+// Returns nil if it finds the object before or at timeout. Otherwise returns a non-nil error
 func WaitForObject(statter ObjectStatter, bucketName, objKey string, tick, timeout time.Duration) error {
 	noExist := errors.New("object doesn't exist")
 	checker := func() error {
@@ -74,6 +75,7 @@ func WaitForObject(statter ObjectStatter, bucketName, objKey string, tick, timeo
 	}
 }
 
+// DownloadObject uses the given getter to download the contents the object at ${bucketName}/${objKey} and returns the object's contents in the given byte slice. Returns nil and the appropriate error if there were problems with the download
 func DownloadObject(getter ObjectGetter, bucketName, objKey string) ([]byte, error) {
 	reader, err := getter.GetObject(bucketName, objKey)
 	if err != nil {

pkg/gitreceive/storage/slug_builder_info.go

@@ -32,12 +32,25 @@ func NewSlugBuilderInfo(s3Endpoint *Endpoint, bucket, appName, slugName string,
 	}
 }
 
-func (s SlugBuilderInfo) PushKey() string               { return s.pushKey }
-func (s SlugBuilderInfo) PushURL() string               { return s.pushURL }
-func (s SlugBuilderInfo) TarKey() string                { return s.tarKey }
-func (s SlugBuilderInfo) TarURL() string                { return s.tarURL }
+// PushKey returns the object storage key that the slug builder will store the slug in. The returned value only contains the path to the folder, not including the final filename.
+func (s SlugBuilderInfo) PushKey() string { return s.pushKey }
+
+// PushURL returns the complete object storage URL that the slug builder will store the slug in. The returned value only contains the URL to the folder, not including the final filename.
+func (s SlugBuilderInfo) PushURL() string { return s.pushURL }
+
+// TarKey returns the object storage key from which the slug builder will download for the tarball (from which it uses to build the slug). The returned value only contains the path to the folder, not including the final filename.
+func (s SlugBuilderInfo) TarKey() string { return s.tarKey }
+
+// TarURL returns the complete object storage URL that the slug builder will download the tarball from. The returned value only contains the URL to the folder, not including the final filename.
+func (s SlugBuilderInfo) TarURL() string { return s.tarURL }
+
+// AbsoluteSlugObjectKey returns the PushKey plus the final filename of the slug
 func (s SlugBuilderInfo) AbsoluteSlugObjectKey() string { return s.PushKey() + "/" + slugTGZName }
-func (s SlugBuilderInfo) AbsoluteProcfileKey() string   { return s.PushKey() + "/Procfile" }
+
+// AbsoluteProcfileKey returns the PushKey plus the standard procfile name
+func (s SlugBuilderInfo) AbsoluteProcfileKey() string { return s.PushKey() + "/Procfile" }
+
+// AbsoluteSlugURL returns the PushURL plus the final filename of the slug
 func (s SlugBuilderInfo) AbsoluteSlugURL() string {
 	return s.PushURL() + "/" + slugTGZName
 }