*: document Client.Namespace

Because we already use the empty string "" to indicate AllNamespaces
it's unclear if the following statement is attempting to list all
namespaces or have the namespace value defaulted:

        client.List(ctx, "", &deployments)

Alternatives such as creating another special variable:

        client.List(ctx, k8s.DefaultNamespace, &deployments)

Seem clunckier than just doing:

        cleint.List(ctx, client.Namespace, &deployments)

Author: ericchiang

client.go

@@ -80,8 +80,27 @@ type Client struct {
 	// The URL of the API server.
 	Endpoint string
 
-	// Default namespaces for objects that don't supply a namespace in
-	// their object metadata.
+	// Namespace is the name fo the default reconciled from the client's config.
+	// It is set when constructing a client using NewClient(), and defaults to
+	// the value "default".
+	//
+	// This value should be used to access the client's default namespace. For
+	// example, to create a configmap in the default namespace, use client.Namespace
+	// when to fill the ObjectMeta:
+	//
+	//		client, err := k8s.NewClient(config)
+	//		if err != nil {
+	//			// handle error
+	//		}
+	//		cm := v1.ConfigMap{
+	//			Metadata: &metav1.ObjectMeta{
+	//				Name:      &k8s.String("my-configmap"),
+	//				Namespace: &client.Namespace,
+	//			},
+	//			Data: map[string]string{"foo": "bar", "spam": "eggs"},
+	//		}
+	//		err := client.Create(ctx, cm)
+	//
 	Namespace string
 
 	// SetHeaders provides a hook for modifying the HTTP headers of all requests.