doc(deis): Add godocs for the deis package (#21)

Author: Joshua-Anderson

deis.go

@@ -1,3 +1,53 @@
+// Package deis offers a SDK for interacting with the Deis controller API.
+//
+// This package works by creating a client, which contains session information,
+// such as the controller url and user token. The client is then passed to api methods,
+// which use it to make requests.
+//
+// Basic Example
+//
+// This example creates a client and then lists the apps that the user has access to:
+//
+//    import (
+//        deis "github.com/deis/controller-sdk-go"
+//        "github.com/deis/controller-sdk-go/apps"
+//    )
+//
+//    //                      Verify SSL, Controller URL, API Token
+//    client, err := deis.New(true, "deis.test.io", "abc123")
+//    if err != nil {
+//        log.Fatal(err)
+//    }
+//    apps, _, err := apps.List(client, 100)
+//    if err != nil {
+//        log.Fatal(err)
+//    }
+//
+// Authentication
+//
+// If you don't already have a token for a user, you can retrieve one with a
+// username and password.
+//
+//    import (
+//        deis "github.com/deis/controller-sdk-go"
+//        "github.com/deis/controller-sdk-go/apps"
+//    )
+//
+//    // Create a client with a blank token to pass to login.
+//    client, err := deis.New(true, "deis.test.io", "")
+//    if err != nil {
+//        log.Fatal(err)
+//    }
+//    token, err := auth.Login(client, "user", "password")
+//    if err != nil {
+//        log.Fatal(err)
+//    }
+//    // Set the client to use the retrieved token
+//    client.Token = token
+//
+// Learning More
+//
+// See the godoc for the SDK's subpackages to learn more about specific SDK actions.
 package deis
 
 import (
@@ -11,26 +61,34 @@ import (
 
 // Client oversees the interaction between the deis and controller
 type Client struct {
-	// HTTP deis used to communicate with the API.
+	// HTTPClient is the transport that is used to communicate with the API.
 	HTTPClient *http.Client
 
 	// VerifySSL determines whether or not to verify SSL connections.
+	// This should be true unless you know the controller is using untrusted SSL keys.
 	VerifySSL bool
 
-	// URL used to communicate with the controller.
+	// ControllerURL is the URL used to communicate with the controller.
 	ControllerURL *url.URL
 
-	//UserAgent is the user agent used when making requests
+	// UserAgent is the user agent used when making requests.
 	UserAgent string
 
-	//API Version used by the controller, set after a http request.
+	// API Version used by the controller, set after a http request.
 	ControllerAPIVersion string
 
 	// Token is used to authenticate the request against the API.
 	Token string
 }
 
-// APIVersion is the api version the sdk is compatible with.
+// APIVersion is the api version compatible with the SDK.
+//
+// In general, using an SDK that is a minor version out of date with the target controller
+// is probably safe, as the deis controller api follows semantic versioning and is backward
+// compatible. However, using a SDK that is newer or a major version different than the
+// controller is unsafe.
+//
+// If the SDK detects an API version mismatch, it will return ErrAPIMismatch.
 const APIVersion = "2.1"
 
 var (
@@ -41,7 +99,10 @@ var (
 	DefaultUserAgent = fmt.Sprintf("Deis Go SDK V%s", APIVersion)
 )
 
-// New creates a new deis to communicate with the api.
+// New creates a new client to communicate with the api.
+// The controllerURL is the url of the controller component, by default deis.<cluster url>.com
+// verifySSL determines whether or not to verify SSL connections.
+// This should be true unless you know the controller is using untrusted SSL keys.
 func New(verifySSL bool, controllerURL string, token string) (*Client, error) {
 	// urlx, unlike the native url library, uses sane defaults when URL parsing,
 	// preventing issues like missing schemes.

errors.go

@@ -80,6 +80,7 @@ var (
 	ErrUnprocessable = errors.New("Unable to process your request.")
 )
 
+// checkForErrors tries to match up an API error with an predefined error in the SDK.
 func checkForErrors(res *http.Response) error {
 	if res.StatusCode >= 200 && res.StatusCode < 400 {
 		return nil

http.go

@@ -21,7 +21,9 @@ func createHTTPClient(sslVerify bool) *http.Client {
 	return &http.Client{Transport: tr}
 }
 
-// Request makes a HTTP request on the controller.
+// Request makes a HTTP request with the given method, relative URL, and body on the controller.
+// It also sets the Authorization and Content-Type headers to properly authenticate and communicate
+// API. This is primarily intended to use be used by the SDK itself, but could potentially be used elsewhere.
 func (c *Client) Request(method string, path string, body []byte) (*http.Response, error) {
 	url := *c.ControllerURL