Refactor the client (again) to better support auth

* Allows consumers to provide their own transports for common cases.
* Supports KUBE_API_VERSION on test cases for controlling which
  api version they test against
* Provides a common flag registration method for CLIs that need
  to connect to an API server (to avoid duplicating flags)
* Ensures errors are properly returned by the server
* Add a Context field to client.Config

pkg/client/doc.go

@@ -14,6 +14,34 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package client contains the implementation of the client side communication with the
-// Kubernetes master.
+/*
+Package client contains the implementation of the client side communication with the
+Kubernetes master. The Client class provides methods for reading, creating, updating,
+and deleting pods, replication controllers, services, and minions.
+
+Most consumers should use the Config object to create a Client:
+
+    config := &client.Config{
+      Host:     "http://localhost:8080",
+      Username: "test",
+      Password: "password",
+    }
+    client, err := client.New(&config)
+    if err != nil {
+      // handle error
+    }
+    client.ListPods()
+
+More advanced consumers may wish to provide their own transport via a http.RoundTripper:
+
+    config := &client.Config{
+      Host:      "https://localhost:8080",
+      Transport: oauthclient.Transport(),
+    }
+    client, err := client.New(&config)
+
+The RESTClient type implements the Kubernetes API conventions (see `docs/api-conventions.md`)
+for a given API path and is intended for use by consumers implementing their own Kubernetes
+compatible APIs.
+*/
 package client