docs(builds): add godocs to package (#24)

Author: Joshua-Anderson

builds/builds.go

@@ -1,3 +1,4 @@
+// Package builds provides methods for managing app builds.
 package builds
 
 import (
@@ -27,7 +28,33 @@ func List(c *deis.Client, appID string, results int) ([]api.Build, int, error) {
 	return builds, count, nil
 }
 
-// New creates a build for an app.
+// New creates a build for an app from an docker image.
+// By default this will create a cmd process that runs the CMD command from the Dockerfile.
+// If you want to define more process types, you can pass a Procfile map,
+// where the key is the process name and the value is the command for that process.
+// To pull from a private docker registry, a custom username and password must be set in the app's
+// configuration object. This can be done with `deis registry:set` or by using this SDK.
+//
+// This example adds custom registry credentials to an app:
+//    import (
+//    	"github.com/deis/controller-sdk-go/api"
+//    	"github.com/deis/controller-sdk-go/config"
+//    )
+//
+//    // Create username/password map
+//    registryMap := map[string]string{
+//    	"username": "password"
+//    }
+//
+//    // Create a new configuration, assign the credentials, and set it.
+//    // Note that config setting is a patching operation, it doesn't overwrite or unset
+//    // unrelated configuration.
+//    newConfig := api.Config{}
+//    newConfig.Registry = registryMap
+//    _, err := config.Set(<client>, "appname", newConfig)
+//    if err != nil {
+//        log.Fatal(err)
+//    }
 func New(c *deis.Client, appID string, image string,
 	procfile map[string]string) (api.Build, error) {