update documentation with new Gophercloud best practices

1 files changed, 56 insertions, 10 deletions

diff --git a/doc.go b/doc.go
index 37ca4f3..1d0dca5 100644
--- a/doc.go
+++ b/doc.go
@@ -21,27 +21,49 @@
 Package schwift is a client library for OpenStack Swift
 (https://github.com/openstack/swift, https://openstack.org).
 
-TODO update doc for changed auth workflow
+Authentication with Gophercloud
 
-It uses Gophercloud (https://github.com/gophercloud/gophercloud) for
-authentication, so you usually start by obtaining a gophercloud.ServiceClient
-for Swift like so:
+Schwift does not implement authentication (neither Keystone nor Swift v1), but
+can be plugged into any library that does. The most common choice is
+Gophercloud (https://github.com/gophercloud/gophercloud).
 
-	authOptions, err := openstack.AuthOptionsFromEnv() // or build a gophercloud.AuthOptions instance yourself
+When using Gophercloud, you usually start by obtaining a
+gophercloud.ServiceClient for Swift like so:
+
+	import (
+		"github.com/gophercloud/gophercloud/openstack"
+		"github.com/gophercloud/utils/openstack/clientconfig"
+	)
+
+	//option 1: build a gophercloud.AuthOptions instance yourself
 	provider, err := openstack.AuthenticatedClient(authOptions)
 	client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{})
 
-Or, if you use Swift's built-in authentication instead of Keystone:
+	//option 2: have Gophercloud read the standard OS_* environment variables
+	provider, err := clientConfig.AuthenticatedClient(nil)
+	client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts{})
 
+	//option 3: if you're using Swift's builtin authentication instead of Keystone
 	provider, err := openstack.NewClient("http://swift.example.com:8080")
 	client, err := swauth.NewObjectStorageV1(provider, swauth.AuthOpts {
 		User: "project:user",
 		Key:  "password",
 	})
 
-Then, in both cases, you use Wrap() from the subpackage gopherschwift to obtain
-a schwift.Account instance, from which point you have access to all of
-schwift's API.
+Then, in all these cases, you use gopherschwift to convert the
+gophercloud.ServiceClient into a schwift.Account instance, from which point you
+have access to all of schwift's API:
+
+	import "github.com/majewsky/schwift/gopherschwift"
+
+	account, err := gopherschwift.Wrap(client)
+
+Authentication with a different OpenStack library
+
+If you use a different Go library to handle Keystone/Swift authentication, take
+the client object that it provides and wrap it into something that implements
+the schwift.Backend interface. Then use schwift.InitializeAccount() to obtain a
+schwift.Account.
 
 Caching
 
@@ -56,7 +78,31 @@ retrieved again.
 	hdr, err = obj.Headers()  //returns cached values immediately
 
 If this behavior is not desired, the Invalidate() method can be used to clear
-caches on any Account, Container or Object instance.
+caches on any Account, Container or Object instance. Some methods that modify
+the instance on the server call Invalidate() automatically, e.g. Object.Upload(),
+Update() or Delete(). This will be indicated in the method's documentation.
+
+Error handling
+
+When a method on an Account, Container or Object instance makes a HTTP request
+to Swift and Swift returns an unexpected status code, a
+schwift.UnexpectedStatusCodeError will be returned. Schwift provides the
+convenience function Is() to check the status code of these errors to detect
+common failure situations:
+
+	obj := account.Container("foo").Object("bar")
+	err := obj.Upload(bytes.NewReader(data), nil)
+
+	if schwift.Is(err, http.StatusRequestEntityTooLarge) {
+		log.Print("quota exceeded for container foo!")
+	} else if err != nil {
+		log.Fatal("unexpected error: " + err.Error())
+	}
+
+The documentation for a method may indicate certain common error conditions
+that can be detected this way by stating that "This method fails with
+http.StatusXXX if ...". Because of the wide variety of failure modes in Swift,
+this information is not guaranteed to be exhaustive.
 
 */
 package schwift