doc: Filled in descriptions for object operations.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>

2 files changed, 164 insertions, 152 deletions

diff --git a/doc/api/s3/bucketops.rst b/doc/api/s3/bucketops.rst
index 9bf7b24fa24..4bb8332ae5b 100644
--- a/doc/api/s3/bucketops.rst
+++ b/doc/api/s3/bucketops.rst
@@ -82,7 +82,6 @@ Returns a list of bucket objects.
 
 Syntax
 ~~~~~~
-
 ::
 
     GET /{bucket}?max-keys=25 HTTP/1.1
@@ -104,7 +103,6 @@ Parameters
 +-----------------+-----------+-----------------------------------------------------------------------+
 
 
-
 HTTP Response
 ~~~~~~~~~~~~~
 
@@ -161,7 +159,6 @@ The ``ListBucketResult`` contains objects, where each object is within a ``Conte
 
 Get Bucket ACL
 --------------
-
 Retrieves the bucket access control list. The user needs to be the bucket
 owner or to have been granted ``READ_ACP`` permission on the bucket.
 
@@ -170,7 +167,6 @@ Syntax
 Add the ``acl`` subresource to the bucket request as shown below.
 
 ::
-
     GET /{bucket}?acl HTTP/1.1
     Host: cname.domain.com
 
@@ -209,7 +205,6 @@ Syntax
 Add the ``acl`` subresource to the bucket request as shown below.
 
 ::
-
     PUT /{bucket}?acl HTTP/1.1
 
 Request Entities
@@ -243,9 +238,7 @@ the service hasn't completed all the uploads yet.
 
 Syntax
 ~~~~~~
-
 ::
-
     GET /{bucket}?uploads HTTP/1.1
 
 Parameters
@@ -285,7 +278,7 @@ Response Entities
 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 | ``KeyMarker``                           | String      | The key marker specified by the ``key-marker`` request parameter (if any).                               |
 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
-| ``UploadIdMarker``                      | String      | The marker specified by the ``upload-id-marker`` request paramter (if any).                              |
+| ``UploadIdMarker``                      | String      | The marker specified by the ``upload-id-marker`` request parameter (if any).                             |
 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
 | ``NextKeyMarker``                       | String      | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``.                            |
 +-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
diff --git a/doc/api/s3/objectops.rst b/doc/api/s3/objectops.rst
index ea25aaf4fd3..857976d1b66 100644
--- a/doc/api/s3/objectops.rst
+++ b/doc/api/s3/objectops.rst
@@ -31,7 +31,7 @@ Request Headers
 
 Copy Object
 -----------
-To copy an object, use PUT and specify a destination bucket and the object name.
+To copy an object, use ``PUT`` and specify a destination bucket and the object name.
 
 Syntax
 ~~~~~~
@@ -88,8 +88,11 @@ Syntax
 
     DELETE /{bucket}/{object} HTTP/1.1
 
+
+
 Get Object
 ----------
+Retrieves an object from a bucket within RADOS. 
 
 Syntax
 ~~~~~~
@@ -101,19 +104,19 @@ Syntax
 Request Headers
 ~~~~~~~~~~~~~~~
 
-+---------------------------+---------------+----------------+------------+
-| Name                      | Description   | Valid Values   | Required   |
-+===========================+===============+================+============+
-| **range**                 |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-modified-since**     |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-unmodified-since**   |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-match**              |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-none-match**         |               |                | No         |
-+---------------------------+---------------+----------------+------------+
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| Name                      | Description                                    | Valid Values                   | Required   |
++===========================+================================================+================================+============+
+| **range**                 | The range of the object to retrieve.           | Range: bytes=beginbyte-endbyte | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-modified-since**     | Gets only if modified since the timestamp.     | Timestamp                      | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-unmodified-since**   | Gets only if not modified since the timestamp. | Timestamp                      | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-match**              | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-none-match**         | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
 
 Response Headers
 ~~~~~~~~~~~~~~~~
@@ -128,8 +131,8 @@ Get Object Info
 ---------------
 
 Returns information about object. This request will return the same
-header information as with the Get Object request, but will not include
-the object data payload.
+header information as with the Get Object request, but will include
+the metadata only, not the object data payload.
 
 Syntax
 ~~~~~~
@@ -141,19 +144,19 @@ Syntax
 Request Headers
 ~~~~~~~~~~~~~~~
 
-+---------------------------+---------------+----------------+------------+
-| Name                      | Description   | Valid Values   | Required   |
-+===========================+===============+================+============+
-| **range**                 |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-modified-since**     |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-unmodified-since**   |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-match**              |               |                | No         |
-+---------------------------+---------------+----------------+------------+
-| **if-none-match**         |               |                | No         |
-+---------------------------+---------------+----------------+------------+
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| Name                      | Description                                    | Valid Values                   | Required   |
++===========================+================================================+================================+============+
+| **range**                 | The range of the object to retrieve.           | Range: bytes=beginbyte-endbyte | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-modified-since**     | Gets only if modified since the timestamp.     | Timestamp                      | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-unmodified-since**   | Gets only if not modified since the timestamp. | Timestamp                      | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-match**              | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
+| **if-none-match**         | Gets only if object ETag matches ETag.         | Entity Tag                     | No         |
++---------------------------+------------------------------------------------+--------------------------------+------------+
 
 Get Object ACL
 --------------
@@ -168,25 +171,27 @@ Syntax
 Response Entities
 ~~~~~~~~~~~~~~~~~
 
-+---------------------------+-------------+---------------+
-| Name                      | Type        | Description   |
-+===========================+=============+===============+
-| **AccessControlPolicy**   | Container   |               |
-+---------------------------+-------------+---------------+
-| **AccessControlList**     | Container   |               |
-+---------------------------+-------------+---------------+
-| **Owner**                 | Container   |               |
-+---------------------------+-------------+---------------+
-| **ID**                    | String      |               |
-+---------------------------+-------------+---------------+
-| **DisplayName**           | String      |               |
-+---------------------------+-------------+---------------+
-| **Grant**                 | Container   |               |
-+---------------------------+-------------+---------------+
-| **Grantee**               | Container   |               |
-+---------------------------+-------------+---------------+
-| **Permission**            | String      |               |
-+---------------------------+-------------+---------------+
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| Name                      | Type        | Description                                                                                  |
++===========================+=============+==============================================================================================+
+| ``AccessControlPolicy``   | Container   | A container for the response.                                                                |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``AccessControlList``     | Container   | A container for the ACL information.                                                         |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Owner``                 | Container   | A container for the object owner's ``ID`` and ``DisplayName``.                               |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``ID``                    | String      | The object owner's ID.                                                                       |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``DisplayName``           | String      | The object owner's display name.                                                             |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Grant``                 | Container   | A container for ``Grantee`` and ``Permission``.                                              |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Grantee``               | Container   | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission.  |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Permission``            | String      | The permission given to the ``Grantee`` object.                                              |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+
+
 
 Set Object ACL
 --------------
@@ -201,25 +206,27 @@ Syntax
 Request Entities
 ~~~~~~~~~~~~~~~~
 
-+---------------------------+-------------+---------------+
-| Name                      | Type        | Description   |
-+===========================+=============+===============+
-| **AccessControlPolicy**   | Container   |               |
-+---------------------------+-------------+---------------+
-| **AccessControlList**     | Container   |               |
-+---------------------------+-------------+---------------+
-| **Owner**                 | Container   |               |
-+---------------------------+-------------+---------------+
-| **ID**                    | String      |               |
-+---------------------------+-------------+---------------+
-| **DisplayName**           | String      |               |
-+---------------------------+-------------+---------------+
-| **Grant**                 | Container   |               |
-+---------------------------+-------------+---------------+
-| **Grantee**               | Container   |               |
-+---------------------------+-------------+---------------+
-| **Permission**            | String      |               |
-+---------------------------+-------------+---------------+
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| Name                      | Type        | Description                                                                                  |
++===========================+=============+==============================================================================================+
+| ``AccessControlPolicy``   | Container   | A container for the response.                                                                |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``AccessControlList``     | Container   | A container for the ACL information.                                                         |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Owner``                 | Container   | A container for the object owner's ``ID`` and ``DisplayName``.                               |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``ID``                    | String      | The object owner's ID.                                                                       |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``DisplayName``           | String      | The object owner's display name.                                                             |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Grant``                 | Container   | A container for ``Grantee`` and ``Permission``.                                              |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Grantee``               | Container   | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission.  |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+| ``Permission``            | String      | The permission given to the ``Grantee`` object.                                              |
++---------------------------+-------------+----------------------------------------------------------------------------------------------+
+
+
 
 Initiate Multi-part Upload
 --------------------------
@@ -236,32 +243,34 @@ Syntax
 Request Headers
 ~~~~~~~~~~~~~~~
 
-+------------------------+---------------+---------------------------------------------------------------+------------+
-| Name                   | Description   | Valid Values                                                  | Required   |
-+========================+===============+===============================================================+============+
-| **content-md5**        |               |                                                               | No         |
-+------------------------+---------------+---------------------------------------------------------------+------------+
-| **content-type**       |               |                                                               | No         |
-+------------------------+---------------+---------------------------------------------------------------+------------+
-| **x-amz-meta-<...>**   |               |                                                               | No         |
-+------------------------+---------------+---------------------------------------------------------------+------------+
-| **x-amz-acl**          |               | private, public-read, public-read-write, authenticated-read   | No         |
-+------------------------+---------------+---------------------------------------------------------------+------------+
++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
+| Name                 | Description                                | Valid Values                                                                  | Required   |
++======================+============================================+===============================================================================+============+
+| **content-md5**      | A base64 encoded MD-5 hash of the message. | A string. No defaults or constraints.                                         | No         |
++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
+| **content-type**     | A standard MIME type.                      | Any MIME type. Default: ``binary/octet-stream``                               | No         |
++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
+| **x-amz-meta-<...>** | User metadata.  Stored with the object.    | A string up to 8kb. No defaults.                                              | No         |
++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
+| **x-amz-acl**        | A canned ACL.                              | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read``   | No         |
++----------------------+--------------------------------------------+-------------------------------------------------------------------------------+------------+
+
 
 Response Entities
 ~~~~~~~~~~~~~~~~~
 
-+-------------------------------------+-------------+---------------+
-| Name                                | Type        | Description   |
-+=====================================+=============+===============+
-| **InitiateMultipartUploadResult**   | Container   |               |
-+-------------------------------------+-------------+---------------+
-| **Bucket**                          | String      |               |
-+-------------------------------------+-------------+---------------+
-| **Key**                             | String      |               |
-+-------------------------------------+-------------+---------------+
-| **UploadId**                        | String      |               |
-+-------------------------------------+-------------+---------------+
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| Name                                    | Type        | Description                                                                                              |
++=========================================+=============+==========================================================================================================+
+| ``InitiatedMultipartUploadsResult``     | Container   | A container for the results.                                                                             |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Bucket``                              | String      | The bucket that will receive the object contents.                                                        |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Key``                                 | String      | The key specified by the ``key`` request parameter (if any).                                             |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``UploadId``                            | String      | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any).       |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+
 
 Multipart Upload Part
 ---------------------
@@ -297,40 +306,49 @@ Syntax
 Response Entities
 ~~~~~~~~~~~~~~~~~
 
-+-------------------------------------+-------------+---------------+
-| Name                                | Type        | Description   |
-+=====================================+=============+===============+
-| **InitiateMultipartUploadResult**   | Container   |               |
-+-------------------------------------+-------------+---------------+
-| **Bucket**                          | String      |               |
-+-------------------------------------+-------------+---------------+
-| **Key**                             | String      |               |
-+-------------------------------------+-------------+---------------+
-| **UploadId**                        | String      |               |
-+-------------------------------------+-------------+---------------+
-| **StorageClass**                    | String      |               |
-+-------------------------------------+-------------+---------------+
-| **PartNumberMarker**                | Integer     |               |
-+-------------------------------------+-------------+---------------+
-| **NextPartNumberMarker**            | Integer     |               |
-+-------------------------------------+-------------+---------------+
-| **MaxParts**                        | Integer     |               |
-+-------------------------------------+-------------+---------------+
-| **IsTruncated**                     | Boolean     |               |
-+-------------------------------------+-------------+---------------+
-| **Part**                            | Container   |               |
-+-------------------------------------+-------------+---------------+
-| **LastModified**                    | Date        |               |
-+-------------------------------------+-------------+---------------+
-| **PartNumber**                      | Integer     |               |
-+-------------------------------------+-------------+---------------+
-| **ETag**                            | String      |               |
-+-------------------------------------+-------------+---------------+
-| **Size**                            | Integer     |               |
-+-------------------------------------+-------------+---------------+
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| Name                                    | Type        | Description                                                                                              |
++=========================================+=============+==========================================================================================================+
+| ``InitiatedMultipartUploadsResult``     | Container   | A container for the results.                                                                             |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Bucket``                              | String      | The bucket that will receive the object contents.                                                        |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Key``                                 | String      | The key specified by the ``key`` request parameter (if any).                                             |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``UploadId``                            | String      | The ID specified by the ``upload-id`` request parameter identifying the multipart upload (if any).       |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Initiator``                           | Container   | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload.                            |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``ID``                                  | String      | The initiator's ID.                                                                                      |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``DisplayName``                         | String      | The initiator's display name.                                                                            |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Owner``                               | Container   | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object.                 |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``StorageClass``                        | String      | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY``                    |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``PartNumberMarker``                    | String      | The part marker to use in a subsequent request if ``IsTruncated`` is ``true``. Precedes the list.        |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``NextPartNumberMarker``                | String      | The next part marker to use in a subsequent request if ``IsTruncated`` is ``true``. The end of the list. |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``MaxParts``                            | Integer     | The max parts allowed in the response as specified by the ``max-parts`` request parameter.               |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``IsTruncated``                         | Boolean     | If ``true``, only a subset of the object's upload contents were returned.                                |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Part``                                | Container   | A container for ``Key``, ``Part``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements.     |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``PartNumber``                          | Integer     | The identification number of the part.                                                                   |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``ETag``                                | String      | The part's entity tag.                                                                                   |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+| ``Size``                                | Integer     | The size of the uploaded part.                                                                           |
++-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
+
+
 
 Complete Multipart Upload
 -------------------------
+Assembles uploaded parts and creates a new object, thereby completing a multipart upload.
 
 Syntax
 ~~~~~~
@@ -342,34 +360,35 @@ Syntax
 Request Entities
 ~~~~~~~~~~~~~~~~
 
-+-------------------------------+-------------+----------------+------------+
-| Name                          | Type        | Valid Values   | Required   |
-+===============================+=============+================+============+
-| **CompleteMultipartUpload**   | Container   |                | Yes        |
-+-------------------------------+-------------+----------------+------------+
-| **Part**                      | Container   |                | Yes        |
-+-------------------------------+-------------+----------------+------------+
-| **PartNumber**                | Integer     |                | Yes        |
-+-------------------------------+-------------+----------------+------------+
-| **ETag**                      | String      |                | Yes        |
-+-------------------------------+-------------+----------------+------------+
++----------------------------------+-------------+-----------------------------------------------------+----------+
+| Name                             | Type        | Description                                         | Required |
++==================================+=============+=====================================================+==========+
+| ``CompleteMultipartUpload``      | Container   | A container consisting of one or more parts.        | Yes      |
++----------------------------------+-------------+-----------------------------------------------------+----------+
+| ``Part``                         | Container   | A container for the ``PartNumber`` and ``ETag``.    | Yes      |
++----------------------------------+-------------+-----------------------------------------------------+----------+
+| ``PartNumber``                   | Integer     | The identifier of the part.                         | Yes      |
++----------------------------------+-------------+-----------------------------------------------------+----------+
+| ``ETag``                         | String      | The part's entity tag.                              | Yes      |
++----------------------------------+-------------+-----------------------------------------------------+----------+
+
 
 Response Entities
 ~~~~~~~~~~~~~~~~~
 
-+-------------------------------------+-------------+---------------+
-| Name                                | Type        | Description   |
-+=====================================+=============+===============+
-| **CompleteMultipartUploadResult**   | Container   |               |
-+-------------------------------------+-------------+---------------+
-| **Location**                        | String      |               |
-+-------------------------------------+-------------+---------------+
-| **Bucket**                          | String      |               |
-+-------------------------------------+-------------+---------------+
-| **Key**                             | String      |               |
-+-------------------------------------+-------------+---------------+
-| **ETag**                            | String      |               |
-+-------------------------------------+-------------+---------------+
++-------------------------------------+-------------+-------------------------------------------------------+
+| Name                                | Type        | Description                                           |
++=====================================+=============+=======================================================+
+| **CompleteMultipartUploadResult**   | Container   | A container for the response.                         |
++-------------------------------------+-------------+-------------------------------------------------------+
+| **Location**                        | URI         | The resource identifier (path) of the new object.     |
++-------------------------------------+-------------+-------------------------------------------------------+
+| **Bucket**                          | String      | The name of the bucket that contains the new object.  |
++-------------------------------------+-------------+-------------------------------------------------------+
+| **Key**                             | String      | The object's key.                                     |
++-------------------------------------+-------------+-------------------------------------------------------+
+| **ETag**                            | String      | The entity tag of the new object.                     |
++-------------------------------------+-------------+-------------------------------------------------------+
 
 Abort Multipart Upload
 ----------------------