docs(config): add godoc for the config package (#25)

Author: Joshua-Anderson

api/config.go

@@ -18,17 +18,32 @@ type ConfigUnset struct {
 
 // Config is the structure of an app's config.
 type Config struct {
-	Owner       string                  `json:"owner,omitempty"`
-	App         string                  `json:"app,omitempty"`
-	Values      map[string]interface{}  `json:"values,omitempty"`
-	Memory      map[string]interface{}  `json:"memory,omitempty"`
-	CPU         map[string]interface{}  `json:"cpu,omitempty"`
+	// Owner is the app owner. It cannot be updated with config.Set(). See app.Transfer().
+	Owner string `json:"owner,omitempty"`
+	// App is the app name. It cannot be updated at all right now.
+	App string `json:"app,omitempty"`
+	// Values are exposed as environment variables to the app.
+	Values map[string]interface{} `json:"values,omitempty"`
+	// Memory is used to set process memory limits. The key is the process name
+	// and the value is a number followed by a memory unit (G, M, K, or B). Ex: 200G
+	Memory map[string]interface{} `json:"memory,omitempty"`
+	// CPU is used to set process CPU limits. It can be set in terms of whole CPUs
+	// (ex 1) or in milli units to reflect the number of CPU shares (ex 500m).
+	CPU map[string]interface{} `json:"cpu,omitempty"`
+	// Healthchecks are the healthchecks that the application uses.
 	Healthcheck map[string]*Healthcheck `json:"healthcheck,omitempty"`
-	Tags        map[string]interface{}  `json:"tags,omitempty"`
-	Registry    map[string]interface{}  `json:"registry,omitempty"`
-	Created     string                  `json:"created,omitempty"`
-	Updated     string                  `json:"updated,omitempty"`
-	UUID        string                  `json:"uuid,omitempty"`
+	// Tags restrict applications to run on k8s nodes with that label.
+	Tags map[string]interface{} `json:"tags,omitempty"`
+	// Registry is a key-value pair to provide authentication for docker registries.
+	// The key is the username and the value is the password.
+	Registry map[string]interface{} `json:"registry,omitempty"`
+	// Created is the time that the application was created and cannot be updated.
+	Created string `json:"created,omitempty"`
+	// Updated is the last time the configuration was changed and cannot be updated.
+	Updated string `json:"updated,omitempty"`
+	// UUID is a unique string reflecting the configuration in its current state.
+	// It changes every time the configuration is changed and cannot be updated.
+	UUID string `json:"uuid,omitempty"`
 }
 
 // Healthcheck is the structure for an application healthcheck.
@@ -56,9 +71,13 @@ Failure Threshold: {{.FailureThreshold}}
 Exec Probe: {{or .Exec "N/A"}}
 HTTP GET Probe: {{or .HTTPGet "N/A"}}
 TCP Socket Probe: {{or .TCPSocket "N/A"}}`)
-	if err != nil { panic(err) }
+	if err != nil {
+		panic(err)
+	}
 	err = tmpl.Execute(&doc, h)
-	if err != nil { panic(err) }
+	if err != nil {
+		panic(err)
+	}
 	return doc.String()
 }
 
@@ -70,7 +89,7 @@ type KVPair struct {
 }
 
 func (k KVPair) String() string {
-	return k.Key+"="+k.Value
+	return k.Key + "=" + k.Value
 }
 
 // ExecProbe executes a command within a Pod.

config/config.go

@@ -1,3 +1,4 @@
+// Package config provides methods for managing configuration of apps.
 package config
 
 import (
@@ -32,7 +33,17 @@ func List(c *deis.Client, app string) (api.Config, error) {
 	return config, nil
 }
 
-// Set sets an app's config variables.
+// Set sets an app's config variables and creates a new release.
+// This is a patching operation, which means when you call Set() with an api.Config:
+//
+//    - If the variable does not exist, it will be set.
+//    - If the variable exists, it will be overwriten.
+//    - If the variable is set to nil, it will be unset.
+//    - If the variable was ignored in the api.Config, it will remain unchanged.
+//
+// Calling Set() with an empty api.Config will return a deis.ErrConflict.
+// Trying to unset a key that does not exist returns a deis.ErrUnprocessable.
+// Trying to set a tag that is not a label in the kubernetes cluster will return a deis.ErrTagNotFound.
 func Set(c *deis.Client, app string, config api.Config) (api.Config, error) {
 	body, err := json.Marshal(config)