revamp the Headers API

1. Move common methods of AccountHeaders, ContainerHeaders,
   ObjectHeaders into a base type Headers.

2. Fold Headers into RequestOptions to remove one of the two optional
   arguments on request methods. The new Headers.ToOpts() method
   offers a nice experience for users passing Headers to request
   methods.

   The Update() methods keep the explicit Headers argument since the
   Headers argument is not optional there.

   The only downside is that we lose a bit of type-safety because
   RequestOptions takes any Headers instance, so e.g. ContainerHeaders
   could be passed to Object.Upload(). I believe the benefits outweigh
   this problem.

1 files changed, 7 insertions, 9 deletions

diff --git a/download.go b/download.go
index 6515bbf..dfd9a07 100644
--- a/download.go
+++ b/download.go
@@ -30,28 +30,26 @@ import (
 //	var obj *swift.Object
 //
 //	//Do NOT do this!
-//	reader, err := obj.Download(nil, nil).AsReadCloser()
+//	reader, err := obj.Download(nil).AsReadCloser()
 //	bytes, err := ioutil.ReadAll(reader)
 //	err := reader.Close()
 //	str := string(bytes)
 //
 //	//Do this instead:
-//	str, err := obj.Download(nil, nil).AsString()
+//	str, err := obj.Download(nil).AsString()
 //
-//Since the AsByteSlice and AsString method consume only the unread portion of
-//the ReadCloser, and since they drain the ReadCloser irreversibly, the
-//idiomatic way of using DownloadedObject is to call one of its members
-//immediately, without storing the DownloadedObject instance in a variable
-//first.
+//Since all methods on DownloadedObject are irreversible, the idiomatic way of
+//using DownloadedObject is to call one of its members immediately, without
+//storing the DownloadedObject instance in a variable first.
 //
 //	var obj *swift.Object
 //
 //	//Do NOT do this!
-//	downloaded := obj.Download(nil, nil)
+//	downloaded := obj.Download(nil)
 //	reader, err := downloaded.AsReadCloser()
 //
 //	//Do this instead:
-//	reader, err := obj.Download(nil, nil).AsReadCloser()
+//	reader, err := obj.Download(nil).AsReadCloser()
 type DownloadedObject struct {
 	r   io.ReadCloser
 	err error