enable autodocumentation for utils module; docstring fixes

This commit adds the utils module to those for which Sphinx
automatically generates documentation from docstrings. (Many of the
functions here may be of little interest to users, but
`generate_temp_url`, at least, definitely deserves to be in the
documentation; in this way, this commit can be seen as a spiritual
companion to ca70dd9e.)

Also, a few markup errors and perceived infelicities in existing
docstrings are amended.

Change-Id: I8c66a23cb359d7dd9302a16459fad9825fedb690

4 files changed, 19 insertions, 14 deletions

diff --git a/doc/source/swiftclient.rst b/doc/source/swiftclient.rst
index 0a07471..e96afba 100644
--- a/doc/source/swiftclient.rst
+++ b/doc/source/swiftclient.rst
@@ -24,3 +24,8 @@ swiftclient.multithreading
 ==========================
 
 .. automodule:: swiftclient.multithreading
+
+swiftclient.utils
+=================
+
+.. automodule:: swiftclient.utils
diff --git a/swiftclient/client.py b/swiftclient/client.py
index 8466cc5..1844914 100644
--- a/swiftclient/client.py
+++ b/swiftclient/client.py
@@ -1011,7 +1011,7 @@ def put_object(url, token=None, container=None, name=None, contents=None,
                       container name is expected to be part of the url
     :param name: object name to put; if None, the object name is expected to be
                  part of the url
-    :param contents: a string, a file like object or an iterable
+    :param contents: a string, a file-like object or an iterable
                      to read object data from;
                      if None, a zero-byte put will be done
     :param content_length: value to send as content-length header; also limits
diff --git a/swiftclient/service.py b/swiftclient/service.py
index c013b90..5d16381 100644
--- a/swiftclient/service.py
+++ b/swiftclient/service.py
@@ -1298,10 +1298,10 @@ class SwiftService(object):
 
                         The SwiftUploadObject source may be one of:
 
-                            file - A file like object (with a read method)
-                            path - A string containing the path to a local file
-                                   or directory
-                            None - Indicates that we want an empty object
+                            * A file-like object (with a read method)
+                            * A string containing the path to a local
+                              file or directory
+                            * None, to indicate that we want an empty object
 
         :param options: A dictionary containing options to override the global
                         options specified during the service object creation.
diff --git a/swiftclient/utils.py b/swiftclient/utils.py
index 8316a8f..05e7f50 100644
--- a/swiftclient/utils.py
+++ b/swiftclient/utils.py
@@ -70,14 +70,14 @@ def generate_temp_url(path, seconds, key, method, absolute=False):
     Swift object.
 
     :param path: The full path to the Swift object. Example:
-    /v1/AUTH_account/c/o.
+        /v1/AUTH_account/c/o.
     :param seconds: The amount of time in seconds the temporary URL will
-    be valid for.
-    :param key: The secret temporary URL key set on the Swift cluster.
-    To set a key, run 'swift post -m
-    "Temp-URL-Key:b3968d0207b54ece87cccc06515a89d4"'
-    :param method: A HTTP method, typically either GET or PUT, to allow for
-    this temporary URL.
+        be valid for.
+    :param key: The secret temporary URL key set on the Swift
+        cluster. To set a key, run 'swift post -m
+        "Temp-URL-Key: <substitute tempurl key here>"'
+    :param method: A HTTP method, typically either GET or PUT, to allow
+        for this temporary URL.
     :raises: ValueError if seconds is not a positive integer
     :raises: TypeError if seconds is not an integer
     :return: the path portion of a temporary URL
@@ -152,7 +152,7 @@ class ReadableToIterable(object):
     Wrap a filelike object and act as an iterator.
 
     It is recommended to use this class only on files opened in binary mode.
-    Due to the Unicode changes in python 3 files are now opened using an
+    Due to the Unicode changes in Python 3, files are now opened using an
     encoding not suitable for use with the md5 class and because of this
     hit the exception on every call to next. This could cause problems,
     especially with large files and small chunk sizes.
@@ -200,7 +200,7 @@ class LengthWrapper(object):
     """
     Wrap a filelike object with a maximum length.
 
-    Fix for https://github.com/kennethreitz/requests/issues/1648
+    Fix for https://github.com/kennethreitz/requests/issues/1648.
     It is recommended to use this class only on files opened in binary mode.
     """
     def __init__(self, readable, length, md5=False):