1 files changed, 62 insertions, 0 deletions
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..d4cb6bd
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,62 @@
+/******************************************************************************
+*
+*  Copyright 2018 Stefan Majewsky <majewsky@gmx.net>
+*
+*  Licensed under the Apache License, Version 2.0 (the "License");
+*  you may not use this file except in compliance with the License.
+*  You may obtain a copy of the License at
+*
+*      http://www.apache.org/licenses/LICENSE-2.0
+*
+*  Unless required by applicable law or agreed to in writing, software
+*  distributed under the License is distributed on an "AS IS" BASIS,
+*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+*  See the License for the specific language governing permissions and
+*  limitations under the License.
+*
+******************************************************************************/
+
+/*
+
+Package schwift is a client library for OpenStack Swift
+(https://github.com/openstack/swift, https://openstack.org).
+
+It uses Gophercloud (https://github.com/gophercloud/gophercloud) for
+authentication, so you usually start by obtaining a gophercloud.ServiceClient
+for Swift like so:
+
+	authOptions, err := openstack.AuthOptionsFromEnv()
+	provider, err := openstack.AuthenticatedClient(authOptions)
+	client, err := openstack.NewObjectStorageV1(provider, gophercloud.EndpointOpts {})
+
+Or, if you use Swift's built-in 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 schwift.AccountFromClient() to obtain a
+schwift.Account instance, from which point you have access to all of schwift's
+API.
+
+Caching
+
+When a GET or HEAD request is sent by an Account, Container or Object instance,
+the metadata associated with that thing will be stored in that instance. You
+can therefore access metadata attributes directly via their accessors and
+everything just works, i.e. the first call to a getter will retrieve the
+metadata:
+
+	obj := account.Container("foo").Object("bar")
+
+	t, err := obj.LastModified() //sends HTTP request "HEAD <storage-url>/foo/bar"
+	assert(err == nil)
+	t, err := obj.LastModified() //returns cached value immediately
+
+If this behavior is not desired, the Invalidate() method can be used to clear
+caches on any Account, Container or Object instance.
+
+*/
+package schwift