aws-sdk 1.8.5 → 1.9.0

data/lib/aws/s3/object_metadata.rb

@@ -35,8 +35,8 @@ module AWS
       # Returns the value for the given name stored in the S3Object's
       # metadata:
       #
-      #   bucket.objects['myobject'].metadata['purpose']
-      #   # returns nil if the given metadata key has not been set
+      #     bucket.objects['myobject'].metadata['purpose']
+      #     # returns nil if the given metadata key has not been set
       #
       # @param [String,Symbol] name The name of the metadata field to
       #   get.
@@ -49,9 +49,9 @@ module AWS
       # Changes the value of the given name stored in the S3Object's
       # metadata:
       #
-      #   object = bucket.object['myobject']
-      #   object.metadata['purpose'] = 'research'
-      #   object.metadata['purpose']               # => 'research'
+      #     object = bucket.object['myobject']
+      #     object.metadata['purpose'] = 'research'
+      #     object.metadata['purpose']               # => 'research'
       #
       # @note The name and value of each metadata field must conform
       #   to US-ASCII.
@@ -80,7 +80,7 @@ module AWS
         self[name]
       end
 
-      # @return [Hash] Returns the user-generated metadata stored with 
+      # @return [Hash] Returns the user-generated metadata stored with
       #   this S3 Object.
       def to_h
         options = {}

data/lib/aws/s3/object_version.rb

@@ -16,8 +16,8 @@ module AWS
 
     # Represents a single version of an S3Object.
     #
-    # When you enable versioning on a S3 bucket, writing to an object 
-    # will create an object version instead of replacing the existing 
+    # When you enable versioning on a S3 bucket, writing to an object
+    # will create an object version instead of replacing the existing
     # object.
     class ObjectVersion
 
@@ -112,14 +112,14 @@ module AWS
       end
 
       # If you delete an object in a versioned bucket, a delete marker
-      # is created.  
+      # is created.
       # @return [Boolean] Returns true if this version is a delete marker.
       def delete_marker?
         if @delete_marker.nil?
           begin
             # S3 responds with a 405 (method not allowed) when you try
             # to HEAD an s3 object version that is a delete marker
-            metadata['foo'] 
+            metadata['foo']
             @delete_marker = false
           rescue Errors::MethodNotAllowed => error
             @delete_marker = true

data/lib/aws/s3/object_version_collection.rb

@@ -17,31 +17,31 @@ module AWS
     # For S3 buckets with versioning enabled, objects will store versions
     # each time you write to them.
     #
-    #   object = bucket.objects['myobj']
-    #   object.write('1')
-    #   object.write('2')
-    #   object.write('3')
+    #     object = bucket.objects['myobj']
+    #     object.write('1')
+    #     object.write('2')
+    #     object.write('3')
     #
-    #   object.versions.collect(&:read)
-    #   #=> ['1', '2', '3']
+    #     object.versions.collect(&:read)
+    #     #=> ['1', '2', '3']
     #
     # To see all the version id for a particular object, access the any particular version,
     # and see the latest version:
     #
-    #   object.versions.each do |version| puts version.version_id end
-    #   #=> T2TwAiZ3SmNr7tOfe0QBa4RZnSb3GSLq
-    #   #=> kAEHC_ysT65bT4P3zyYOP1ELA6ajar_6
-    #   #=> itHPX6m8na_sog0cAtkgP3QITEE8v5ij
+    #     object.versions.each do |version| puts version.version_id end
+    #     #=> T2TwAiZ3SmNr7tOfe0QBa4RZnSb3GSLq
+    #     #=> kAEHC_ysT65bT4P3zyYOP1ELA6ajar_6
+    #     #=> itHPX6m8na_sog0cAtkgP3QITEE8v5ij
     #
-    #   object.versions['itHPX6m8na_sog0cAtkgP3QITEE8v5ij']
-    #   #=> <AWS::S3::ObjectVersion:<<bucket>>:myobj:itHPX6m8na_sog0cAtkgP3QITEE8v5ij>
+    #     object.versions['itHPX6m8na_sog0cAtkgP3QITEE8v5ij']
+    #     #=> <AWS::S3::ObjectVersion:<<bucket>>:myobj:itHPX6m8na_sog0cAtkgP3QITEE8v5ij>
     #
-    #   object.versions.latest
-    #   #=> <AWS::S3::ObjectVersion:<<bucket>>:myobj:T2TwAiZ3SmNr7tOfe0QBa4RZnSb3GSLq>
+    #     object.versions.latest
+    #     #=> <AWS::S3::ObjectVersion:<<bucket>>:myobj:T2TwAiZ3SmNr7tOfe0QBa4RZnSb3GSLq>
     #
     # If you know the id of a particular version you can get that object.
     #
-    #   bucket.objects['myobj'].version[version_id].delete
+    #     bucket.objects['myobj'].version[version_id].delete
     #
     class ObjectVersionCollection
 

data/lib/aws/s3/policy.rb

@@ -58,11 +58,11 @@ module AWS
             "#{prefix}#{resource.name}"
           when S3Object
             "#{prefix}#{resource.bucket.name}/#{resource.key}"
-          when ObjectCollection 
+          when ObjectCollection
             "#{prefix}#{resource.bucket.name}/#{resource.prefix}*"
           when /^arn:/
             resource
-          else 
+          else
             "arn:aws:s3:::#{resource}"
           end
         end

data/lib/aws/s3/prefixed_collection.rb

@@ -25,36 +25,40 @@ module AWS
         args.push(options)
         super(*args)
       end
-        
+
       # @return [String,nil] The prefix of this collection.
       attr_reader :prefix
 
       # Returns a new collection with a different prefix
       #
       # @example
+      #
       #   objects = collection.with_prefix('photos')
       #   objects.prefix #=> 'photos'
       #
       # @example Chaining with_prefix replaces previous prefix
+      #
       #   objects = collection.with_prefix('photos').with_prefix('videos')
       #   objects.prefix #=> 'videos'
       #
       # @example Chaining with_prefix with :append
+      #
       #   objects = collection.with_prefix('a/').with_prefix('b/', :append)
       #   objects.prefix #=> 'a/b/'
       #
       # @example Chaining with_prefix with :prepend
+      #
       #   objects = collection.with_prefix('a/').with_prefix('b/', :prepend)
       #   objects.prefix #=> 'b/a/'
       #
       # @param [String] prefix The prefix condition that limits what objects
       #   are returned by this collection.
       # @param [Symbol] mode (:replace) If you chain calls to #with_prefix
-      #   the +mode+ affects if the prefix prepends, appends, or replaces.
+      #   the `mode` affects if the prefix prepends, appends, or replaces.
       #   Valid modes are:
-      #   * +:replace+
-      #   * +:append+
-      #   * +:prepend+
+      #   * `:replace`
+      #   * `:append`
+      #   * `:prepend`
       # @return [Collection] Returns a new collection with a modified prefix.
       def with_prefix prefix, mode = :replace
         new_prefix = case mode

data/lib/aws/s3/presigned_post.rb

@@ -43,9 +43,11 @@ module AWS
     #   END
     #
     # @example Restricting the size of the uploaded object
+    #
     #   bucket.presigned_post(:content_length => 1..(10*1024))
     #
     # @example Restricting the key prefix
+    #
     #   bucket.presigned_post.where(:key).starts_with("photos/")
     #
     class PresignedPost
@@ -103,7 +105,7 @@ module AWS
       #   using the form fields.
       #
       # @param [Hash] opts Additional options for the upload.  Aside
-      #   from +:secure+, +:expires+, +:content_length+ and +:ignore+
+      #   from `:secure`, `:expires`, `:content_length` and `:ignore`
       #   the values provided here will be stored in the hash returned
       #   from the {#fields} method, and the policy in that hash will
       #   restrict their values to the values provided.  If you
@@ -148,19 +150,19 @@ module AWS
       #
       # @option options [Symbol] :acl A canned access control
       #   policy.  Valid values are:
-      #   * +:private+
-      #   * +:public_read+
-      #   * +:public_read_write+
-      #   * +:authenticated_read+
-      #   * +:bucket_owner_read+
-      #   * +:bucket_owner_full_control+
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read`
+      #   * `:bucket_owner_full_control`
       #
       # @option options [Symbol] :server_side_encryption (nil) If this
       #   option is set, the object will be stored using server side
-      #   encryption.  The only valid value is +:aes256+, which
+      #   encryption.  The only valid value is `:aes256`, which
       #   specifies that the object should be stored using the AES
       #   encryption algorithm with 256 bit keys.  By default, this
-      #   option uses the value of the +:s3_server_side_encryption+
+      #   option uses the value of the `:s3_server_side_encryption`
       #   option in the current configuration; for more information,
       #   see {AWS.config}.
       #
@@ -169,7 +171,7 @@ module AWS
       #
       # @option opts [Integer] :success_action_status The status
       #   code returned to the client upon successful upload if
-      #   +:success_action_redirect+ is not specified.  Accepts the
+      #   `:success_action_redirect` is not specified.  Accepts the
       #   values 200, 201, or 204 (default).
       #
       #   If the value is set to 200 or 204, Amazon S3 returns an
@@ -178,7 +180,7 @@ module AWS
       #   If the value is set to 201, Amazon S3 returns an XML
       #   document with a 201 status code.  For information on the
       #   content of the XML document, see
-      #   {POST Object}[http://docs.amazonwebservices.com/AmazonS3/2006-03-01/API/index.html?RESTObjectPOST.html].
+      #   [POST Object](http://docs.amazonwebservices.com/AmazonS3/2006-03-01/API/index.html?RESTObjectPOST.html).
       #
       # @option opts [Hash] :metadata A hash of the metadata fields
       #   included in the signed fields.  Additional metadata fields
@@ -223,7 +225,7 @@ module AWS
 
       # @return [URI::HTTP, URI::HTTPS] The URL to which the form
       #   fields should be POSTed.  If you are using the fields in
-      #   an HTML form, this is the URL to put in the +action+
+      #   an HTML form, this is the URL to put in the `action`
       #   attribute of the form tag.
       def url
         req = Request.new
@@ -255,17 +257,17 @@ module AWS
         # Specifies that the value of the field must begin with the
         # provided value.  If you are specifying a condition on the
         # "key" field, note that this check takes place after the
-        # +${filename}+ variable is expanded.  This is only valid
+        # `${filename}` variable is expanded.  This is only valid
         # for the following fields:
         #
-        # * +:key+
-        # * +:cache_control+
-        # * +:content_type+
-        # * +:content_disposition+
-        # * +:content_encoding+
-        # * +:expires_header+
-        # * +:acl+
-        # * +:success_action_redirect+
+        # * `:key`
+        # * `:cache_control`
+        # * `:content_type`
+        # * `:content_disposition`
+        # * `:content_encoding`
+        # * `:expires_header`
+        # * `:acl`
+        # * `:success_action_redirect`
         # * metadata fields (see {#where_metadata})
         def starts_with(prefix)
           @post.with_prefix_condition(@field, prefix)
@@ -273,8 +275,8 @@ module AWS
 
         # Specifies that the value of the field must be in the given
         # range.  This may only be used to constrain the
-        # +:content_length+ field,
-        # e.g. <tt>presigned_post.with(:conent_length).in(1..4)</tt>.
+        # `:content_length` field,
+        # e.g. `presigned_post.with(:conent_length).in(1..4)`.
         def in(range)
           @post.refine(:content_length => range)
         end
@@ -290,16 +292,16 @@ module AWS
       # @param [Symbol] field The field for which a condition should
       #  be added.  Valid values:
       #
-      #  * +:key+
-      #  * +:content_length+
-      #  * +:cache_control+
-      #  * +:content_type+
-      #  * +:content_disposition+
-      #  * +:content_encoding+
-      #  * +:expires_header+
-      #  * +:acl+
-      #  * +:success_action_redirect+
-      #  * +:success_action_status+
+      #  * `:key`
+      #  * `:content_length`
+      #  * `:cache_control`
+      #  * `:content_type`
+      #  * `:content_disposition`
+      #  * `:content_encoding`
+      #  * `:expires_header`
+      #  * `:acl`
+      #  * `:success_action_redirect`
+      #  * `:success_action_status`
       #
       # @return [ConditionBuilder] An object that allows you to
       #   specify a condition on the field.
@@ -317,7 +319,7 @@ module AWS
       # then S3 will reject it.
       #
       # @param [Symbol, String] field The name of the metadata
-      #   attribute.  For example, +:color+ corresponds to the
+      #   attribute.  For example, `:color` corresponds to the
       #   "x-amz-meta-color" field in the POST body.
       #
       # @return [ConditionBuilder] An object that allows you to
@@ -494,14 +496,14 @@ module AWS
 
         conditions = self.conditions.inject([]) do |list, (field, field_conds)|
           list + field_conds
-        end 
-        
+        end
+
         conditions << { "bucket" => bucket.name }
         conditions += key_conditions
         conditions += optional_fields.map { |(n, v)| Hash[[[n, v]]] }
         conditions += range_conditions
         conditions += ignored_conditions
-        
+
         if token = config.credential_provider.session_token
           conditions << { "x-amz-security-token" => token }
         end

data/lib/aws/s3/request.rb

@@ -83,12 +83,12 @@ module AWS
 
       # From the S3 developer guide:
       #
-      # StringToSign =
-      #   HTTP-Verb + "\n" +
-      #   content-md5 + "\n" +
-      #   content-type + "\n" +
-      #   date + "\n" +
-      #   CanonicalizedAmzHeaders + CanonicalizedResource;
+      #     StringToSign =
+      #       HTTP-Verb ` "\n" `
+      #       content-md5 ` "\n" `
+      #       content-type ` "\n" `
+      #       date ` "\n" `
+      #       CanonicalizedAmzHeaders + CanonicalizedResource;
       #
       def string_to_sign
         [
@@ -112,11 +112,11 @@ module AWS
 
       # From the S3 developer guide
       #
-      #   CanonicalizedResource =
-      #     [ "/" + Bucket ] +
-      #     <HTTP-Request-URI, from the protocol name up to the querystring> +
-      #     [ sub-resource, if present. e.g. "?acl", "?location",
-      #     "?logging", or "?torrent"];
+      #     CanonicalizedResource =
+      #       [ "/" ` Bucket ] `
+      #       <HTTP-Request-URI, from the protocol name up to the querystring> +
+      #       [ sub-resource, if present. e.g. "?acl", "?location",
+      #       "?logging", or "?torrent"];
       #
       def canonicalized_resource
 

data/lib/aws/s3/s3_object.rb

@@ -20,57 +20,57 @@ module AWS
     # Represents an object in S3.  Objects live in a bucket and have
     # unique keys.
     #
-    # = Getting Objects
+    # # Getting Objects
     #
     # You can get an object by its key.
     #
-    #   s3 = AWS::S3.new
-    #   obj = s3.buckets['my-bucket'].objects['key'] # no request made
+    #     s3 = AWS::S3.new
+    #     obj = s3.buckets['my-bucket'].objects['key'] # no request made
     #
     # You can also get objects by enumerating a objects in a bucket.
     #
-    #   bucket.objects.each do |obj|
-    #     puts obj.key
-    #   end
+    #     bucket.objects.each do |obj|
+    #       puts obj.key
+    #     end
     #
     # See {ObjectCollection} for more information on finding objects.
     #
-    # = Creating Objects
+    # # Creating Objects
     #
     # You create an object by writing to it.  The following two
     # expressions are equivalent.
     #
-    #   obj = bucket.objects.create('key', 'data')
-    #   obj = bucket.objects['key'].write('data')
+    #     obj = bucket.objects.create('key', 'data')
+    #     obj = bucket.objects['key'].write('data')
     #
-    # = Writing Objects
+    # # Writing Objects
     #
     # To upload data to S3, you simply need to call {#write} on an object.
     #
-    #    obj.write('Hello World!')
-    #    obj.read
-    #    #=> 'Hello World!'
+    #     obj.write('Hello World!')
+    #     obj.read
+    #     #=> 'Hello World!'
     #
-    # == Uploading Files
+    # ## Uploading Files
     #
     # You can upload a file to S3 in a variety of ways.  Given a path
     # to a file (as a string) you can do any of the following:
     #
-    #   # specify the data as a path to a file
-    #   obj.write(Pathname.new(path_to_file))
+    #     # specify the data as a path to a file
+    #     obj.write(Pathname.new(path_to_file))
     #
-    #   # also works this way
-    #   obj.write(:file => path_to_file)
+    #     # also works this way
+    #     obj.write(:file => path_to_file)
     #
-    #   # Also accepts an open file object
-    #   file = File.open(path_to_file, 'r')
-    #   obj.write(file)
+    #     # Also accepts an open file object
+    #     file = File.open(path_to_file, 'r')
+    #     obj.write(file)
     #
     # All three examples above produce the same result.  The file
     # will be streamed to S3 in chunks.  It will not be loaded
     # entirely into memory.
     #
-    # == Streaming Uploads
+    # ## Streaming Uploads
     #
     # When you call {#write} with any IO-like object (must respond to
     # #read and #eof?), it will be streamed to S3 in chunks.
@@ -78,160 +78,160 @@ module AWS
     # While it is possible to determine the size of many IO objects, you may
     # have to specify the :content_length of your IO object.
     # If the exact size can not be known, you may provide an
-    # +:estimated_content_length+.  Depending on the size (actual or
+    # `:estimated_content_length`.  Depending on the size (actual or
     # estimated) of your data, it will be uploaded in a single request or
     # in multiple requests via {#multipart_upload}.
     #
     # You may also stream uploads to S3 using a block:
     #
-    #   obj.write do |buffer, bytes|
-    #     # writing fewer than the requested number of bytes to the buffer
-    #     # will cause write to stop yielding to the block
-    #   end
+    #     obj.write do |buffer, bytes|
+    #       # writing fewer than the requested number of bytes to the buffer
+    #       # will cause write to stop yielding to the block
+    #     end
     #
-    # = Reading Objects
+    # # Reading Objects
     #
     # You can read an object directly using {#read}.  Be warned, this will
     # load the entire object into memory and is not recommended for large
     # objects.
     #
-    #   obj.write('abc')
-    #   puts obj.read
-    #   #=> abc
+    #     obj.write('abc')
+    #     puts obj.read
+    #     #=> abc
     #
-    # == Streaming Downloads
+    # ## Streaming Downloads
     #
     # If you want to stream an object from S3, you can pass a block
     # to {#read}.
     #
-    #   File.open('output', 'w') do |file|
-    #     large_object.read do |chunk|
-    #       file.write(chunk)
+    #     File.open('output', 'w') do |file|
+    #       large_object.read do |chunk|
+    #         file.write(chunk)
+    #       end
     #     end
-    #   end
     #
-    # = Encryption
+    # # Encryption
     #
     # Amazon S3 can encrypt objects for you service-side.  You can also
     # use client-side encryption.
     #
-    # == Server Side Encryption
+    # ## Server Side Encryption
     #
     # Amazon S3 provides server side encryption for an additional cost.
     # You can specify to use server side encryption when writing an object.
     #
-    #   obj.write('data', :server_side_encryption => :aes256)
+    #     obj.write('data', :server_side_encryption => :aes256)
     #
     # You can also make this the default behavior.
     #
-    #   AWS.config(:s3_server_side_encryption => :aes256)
+    #     AWS.config(:s3_server_side_encryption => :aes256)
     #
-    #   s3 = AWS::S3.new
-    #   s3.buckets['name'].objects['key'].write('abc') # will be encrypted
+    #     s3 = AWS::S3.new
+    #     s3.buckets['name'].objects['key'].write('abc') # will be encrypted
     #
-    # == Client Side Encryption
+    # ## Client Side Encryption
     #
     # Client side encryption utilizes envelope encryption, so that your keys are
     # never sent to S3.  You can use a symetric key or an asymmetric
     # key pair.
     #
-    # === Symmetric Key Encryption
+    # ### Symmetric Key Encryption
     #
     # An AES key is used for symmetric encryption.  The key can be 128, 192,
     # and 256 bit sizes. Start by generating key or read a previously
     # generated key.
     #
-    #   # generate a new random key
-    #   my_key = OpenSSL::Cipher.new("AES-256-ECB").random_key
+    #     # generate a new random key
+    #     my_key = OpenSSL::Cipher.new("AES-256-ECB").random_key
     #
-    #   # read an existing key from disk
-    #   my_key = File.read("my_key.der")
+    #     # read an existing key from disk
+    #     my_key = File.read("my_key.der")
     #
     # Now you can encrypt locally and upload the encrypted data to S3.
     # To do this, you need to provide your key.
     #
-    #   obj = bucket.objects["my-text-object"]
+    #     obj = bucket.objects["my-text-object"]
     #
-    #   # encrypt then upload data
-    #   obj.write("MY TEXT", :encryption_key => my_key)
+    #     # encrypt then upload data
+    #     obj.write("MY TEXT", :encryption_key => my_key)
     #
-    #   # try read the object without decrypting, oops
-    #   obj.read
-    #   #=> '.....'
+    #     # try read the object without decrypting, oops
+    #     obj.read
+    #     #=> '.....'
     #
     # Lastly, you can download and decrypt by providing the same key.
     #
-    #   obj.read(:encryption_key => my_key)
-    #   #=> "MY TEXT"
+    #     obj.read(:encryption_key => my_key)
+    #     #=> "MY TEXT"
     #
-    # === Asymmetric Key Pair
+    # ### Asymmetric Key Pair
     #
     # A RSA key pair is used for asymmetric encryption.  The public key is used
     # for encryption and the private key is used for decryption.  Start
     # by generating a key.
     #
-    #   my_key = OpenSSL::PKey::RSA.new(1024)
+    #     my_key = OpenSSL::PKey::RSA.new(1024)
     #
     # Provide your key to #write and the data will be encrypted before it
     # is uploaded. Pass the same key to #read to decrypt the data
     # when you download it.
     #
-    #   obj = bucket.objects["my-text-object"]
+    #     obj = bucket.objects["my-text-object"]
     #
-    #   # encrypt and upload the data
-    #   obj.write("MY TEXT", :encryption_key => my_key)
+    #     # encrypt and upload the data
+    #     obj.write("MY TEXT", :encryption_key => my_key)
     #
-    #   # download and decrypt the data
-    #   obj.read(:encryption_key => my_key)
-    #   #=> "MY TEXT"
+    #     # download and decrypt the data
+    #     obj.read(:encryption_key => my_key)
+    #     #=> "MY TEXT"
     #
-    # === Configuring storage locations
+    # ### Configuring storage locations
     #
     # By default, encryption materials are stored in the object metadata.
     # If you prefer, you can store the encryption materials in a separate
     # object in S3.  This object will have the same key + '.instruction'.
     #
-    #   # new object, does not exist yet
-    #   obj = bucket.objects["my-text-object"]
+    #     # new object, does not exist yet
+    #     obj = bucket.objects["my-text-object"]
     #
-    #   # no instruction file present
-    #   bucket.objects['my-text-object.instruction'].exists?
-    #   #=> false
+    #     # no instruction file present
+    #     bucket.objects['my-text-object.instruction'].exists?
+    #     #=> false
     #
-    #   # store the encryption materials in the instruction file
-    #   # instead of obj#metadata
-    #   obj.write("MY TEXT",
-    #     :encryption_key => MY_KEY,
-    #     :encryption_materials_location => :instruction_file)
+    #     # store the encryption materials in the instruction file
+    #     # instead of obj#metadata
+    #     obj.write("MY TEXT",
+    #       :encryption_key => MY_KEY,
+    #       :encryption_materials_location => :instruction_file)
     #
-    #   bucket.objects['my-text-object.instruction'].exists?
-    #   #=> true
+    #     bucket.objects['my-text-object.instruction'].exists?
+    #     #=> true
     #
     # If you store the encryption materials in an instruction file, you
     # must tell #read this or it will fail to find your encryption materials.
     #
-    #   # reading an encrypted file whos materials are stored in an
-    #   # instruction file, and not metadata
-    #   obj.read(:encryption_key => MY_KEY,
-    #     :encryption_materials_location => :instruction_file)
+    #     # reading an encrypted file whos materials are stored in an
+    #     # instruction file, and not metadata
+    #     obj.read(:encryption_key => MY_KEY,
+    #       :encryption_materials_location => :instruction_file)
     #
-    # === Configuring default behaviors
+    # ### Configuring default behaviors
     #
     # You can configure the default key such that it will automatically
     # encrypt and decrypt for you.  You can do this globally or for a
     # single S3 interface
     #
-    #   # all objects uploaded/downloaded with this s3 object will be 
-    #   # encrypted/decrypted
-    #   s3 = AWS::S3.new(:s3_encryption_key => "MY_KEY")
+    #     # all objects uploaded/downloaded with this s3 object will be
+    #     # encrypted/decrypted
+    #     s3 = AWS::S3.new(:s3_encryption_key => "MY_KEY")
     #
-    #   # set the key to always encrypt/decrypt
-    #   AWS.config(:s3_encryption_key => "MY_KEY")
+    #     # set the key to always encrypt/decrypt
+    #     AWS.config(:s3_encryption_key => "MY_KEY")
     #
     # You can also configure the default storage location for the encryption
     # materials.
     #
-    #   AWS.config(:s3_encryption_materials_location => :instruction_file)
+    #     AWS.config(:s3_encryption_materials_location => :instruction_file)
     #
     class S3Object
 
@@ -266,7 +266,7 @@ module AWS
       end
       alias_method :eql?, :==
 
-      # @return [Boolean] Returns +true+ if the object exists in S3.
+      # @return [Boolean] Returns `true` if the object exists in S3.
       def exists?
         head
       rescue Errors::NoSuchKey => e
@@ -283,7 +283,7 @@ module AWS
       # * content_type (as sent to S3 when uploading the object)
       # * etag (typically the object's MD5)
       # * server_side_encryption (the algorithm used to encrypt the
-      #   object on the server side, e.g. +:aes256+)
+      #   object on the server side, e.g. `:aes256`)
       #
       # @param [Hash] options
       # @option options [String] :version_id Which version of this object
@@ -337,7 +337,7 @@ module AWS
       end
 
       # @return [Symbol, nil] Returns the algorithm used to encrypt
-      #   the object on the server side, or +nil+ if SSE was not used
+      #   the object on the server side, or `nil` if SSE was not used
       #   when storing the object.
       def server_side_encryption
         head[:server_side_encryption]
@@ -382,7 +382,7 @@ module AWS
       #   of this object will be deleted.  Only works for buckets that have
       #   had versioning enabled.
       #
-      # @option [Boolean] :delete_instruction_file (false) Set this to +true+
+      # @option [Boolean] :delete_instruction_file (false) Set this to `true`
       #   if you use client-side encryption and the encryption materials
       #   were stored in a separate object in S3 (key.instruction).
       #
@@ -407,7 +407,7 @@ module AWS
       end
 
       # Restores a temporary copy of an archived object from the
-      # Glacier storage tier. After the specified +days+, Amazon
+      # Glacier storage tier. After the specified `days`, Amazon
       # S3 deletes the temporary copy. Note that the object
       # remains archived; Amazon S3 deletes only the restored copy.
       #
@@ -415,7 +415,7 @@ module AWS
       # {#restore_in_progress?} to check the status of the operation.
       #
       # @option [Integer] :days (1) the number of days to keep the object
-      # @return [Boolean] +true+ if a restore can be initiated.
+      # @return [Boolean] `true` if a restore can be initiated.
       # @since 1.7.2
       def restore options = {}
         options[:days] ||= 1
@@ -439,6 +439,8 @@ module AWS
       # Returns a collection representing all the object versions
       # for this object.
       #
+      # @example
+      #
       #   bucket.versioning_enabled? # => true
       #   version = bucket.objects["mykey"].versions.latest
       #
@@ -449,32 +451,32 @@ module AWS
 
       # Uploads data to the object in S3.
       #
-      #   obj = s3.buckets['bucket-name'].objects['key']
+      #     obj = s3.buckets['bucket-name'].objects['key']
       #
-      #   # strings
-      #   obj.write("HELLO")
+      #     # strings
+      #     obj.write("HELLO")
       #
-      #   # files (by path)
-      #   obj.write(Pathname.new('path/to/file.txt'))
+      #     # files (by path)
+      #     obj.write(Pathname.new('path/to/file.txt'))
       #
-      #   # file objects
-      #   obj.write(File.open('path/to/file.txt', 'r'))
+      #     # file objects
+      #     obj.write(File.open('path/to/file.txt', 'r'))
       #
-      #   # IO objects (must respond to #read and #eof?)
-      #   obj.write(io)
+      #     # IO objects (must respond to #read and #eof?)
+      #     obj.write(io)
       #
-      # === Multipart Uploads vs Single Uploads
+      # ### Multipart Uploads vs Single Uploads
       #
       # This method will intelligently choose between uploading the
       # file in a signal request and using {#multipart_upload}.
       # You can control this behavior by configuring the thresholds
       # and you can disable the multipart feature as well.
       #
-      #   # always send the file in a single request
-      #   obj.write(file, :single_request => true)
+      #     # always send the file in a single request
+      #     obj.write(file, :single_request => true)
       #
-      #   # upload the file in parts if the total file size exceeds 100MB
-      #   obj.write(file, :multipart_threshold => 100 * 1024 * 1024)
+      #     # upload the file in parts if the total file size exceeds 100MB
+      #     obj.write(file, :multipart_threshold => 100 * 1024 * 1024)
       #
       # @overload write(data, options = {})
       #
@@ -484,25 +486,25 @@ module AWS
       #     * Pathname
       #     * File
       #     * IO
-      #     * Any object that responds to +#read+ and +#eof?+.
+      #     * Any object that responds to `#read` and `#eof?`.
       #
       #   @param options [Hash] Additional upload options.
       #
       #   @option options [Integer] :content_length If provided, this
       #     option must match the total number of bytes written to S3.
       #     This options is *required* when it is not possible to
-      #     automatically determine the size of +data+.
+      #     automatically determine the size of `data`.
       #
       #   @option options [Integer] :estimated_content_length When uploading
       #     data of unknown content length, you may specify this option to
       #     hint what mode of upload should take place.  When
-      #     +:estimated_content_length+ exceeds the +:multipart_threshold+,
+      #     `:estimated_content_length` exceeds the `:multipart_threshold`,
       #     then the data will be uploaded in parts, otherwise it will
       #     be read into memory and uploaded via {Client#put_object}.
       #
-      #   @option options [Boolean] :single_request (false) When +true+,
+      #   @option options [Boolean] :single_request (false) When `true`,
       #     this method will always upload the data in a single request
-      #     (via {Client#put_object}).  When +false+, this method will
+      #     (via {Client#put_object}).  When `false`, this method will
       #     choose between {Client#put_object} and {#multipart_upload}.
       #
       #   @option options [Integer] :multipart_threshold (16777216) Specifies
@@ -519,18 +521,18 @@ module AWS
       #
       #   @option options [Hash] :metadata A hash of metadata to be
       #     included with the object.  These will be sent to S3 as
-      #     headers prefixed with +x-amz-meta+.  Each name, value pair
+      #     headers prefixed with `x-amz-meta`.  Each name, value pair
       #     must conform to US-ASCII.
       #
       #   @option options [Symbol,String] :acl (:private) A canned access
       #     control policy.  Valid values are:
       #
-      #     * +:private+
-      #     * +:public_read+
-      #     * +:public_read_write+
-      #     * +:authenticated_read+
-      #     * +:bucket_owner_read+
-      #     * +:bucket_owner_full_control+
+      #     * `:private`
+      #     * `:public_read`
+      #     * `:public_read_write`
+      #     * `:authenticated_read`
+      #     * `:bucket_owner_read`
+      #     * `:bucket_owner_full_control`
       #
       #   @option options [String] :grant_read
       #
@@ -542,7 +544,7 @@ module AWS
       #
       #   @option options [String] :grant_full_control
       #
-      #   @option options [Boolean] :reduced_redundancy (false) When +true+,
+      #   @option options [Boolean] :reduced_redundancy (false) When `true`,
       #     this object will be stored with Reduced Redundancy Storage.
       #
       #   @option options :cache_control [String] Can be used to specify
@@ -556,7 +558,7 @@ module AWS
       #   @option options :content_encoding [String] Specifies what
       #     content encodings have been applied to the object and thus
       #     what decoding mechanisms must be applied to obtain the
-      #     media-type referenced by the +Content-Type+ header field.
+      #     media-type referenced by the `Content-Type` header field.
       #     See
       #     http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
       #
@@ -568,10 +570,10 @@ module AWS
       #
       #   @option options [Symbol] :server_side_encryption (nil) If this
       #     option is set, the object will be stored using server side
-      #     encryption.  The only valid value is +:aes256+, which
+      #     encryption.  The only valid value is `:aes256`, which
       #     specifies that the object should be stored using the AES
       #     encryption algorithm with 256 bit keys.  By default, this
-      #     option uses the value of the +:s3_server_side_encryption+
+      #     option uses the value of the `:s3_server_side_encryption`
       #     option in the current configuration; for more information,
       #     see {AWS.config}.
       #
@@ -581,7 +583,7 @@ module AWS
       #     or a symmetric key string (16, 24 or 32 bytes in length).
       #
       #   @option options [Symbol] :encryption_materials_location (:metadata)
-      #     Set this to +:instruction_file+ if you prefer to store the
+      #     Set this to `:instruction_file` if you prefer to store the
       #     client-side encryption materials in a separate object in S3
       #     instead of in the object metadata.
       #
@@ -590,7 +592,7 @@ module AWS
       #
       # @return [S3Object, ObjectVersion] If the bucket has versioning
       #   enabled, this methods returns an {ObjectVersion}, otherwise
-      #   this method returns +self+.
+      #   this method returns `self`.
       #
       def write *args, &block
 
@@ -615,24 +617,28 @@ module AWS
       # to use.
       #
       # @example Uploading an object in two parts
+      #
       #   bucket.objects.myobject.multipart_upload do |upload|
       #     upload.add_part("a" * 5242880)
       #     upload.add_part("b" * 2097152)
       #   end
       #
       # @example Uploading parts out of order
+      #
       #   bucket.objects.myobject.multipart_upload do |upload|
       #     upload.add_part("b" * 2097152, :part_number => 2)
       #     upload.add_part("a" * 5242880, :part_number => 1)
       #   end
       #
       # @example Aborting an upload after parts have been added
+      #
       #   bucket.objects.myobject.multipart_upload do |upload|
       #     upload.add_part("b" * 2097152, :part_number => 2)
       #     upload.abort
       #   end
       #
       # @example Starting an upload and completing it later by ID
+      #
       #   upload = bucket.objects.myobject.multipart_upload
       #   upload.add_part("a" * 5242880)
       #   upload.add_part("b" * 2097152)
@@ -643,7 +649,7 @@ module AWS
       #   upload.complete(:remote_parts)
       #
       # @yieldparam [MultipartUpload] upload A handle to the upload.
-      #   {MultipartUpload#close} is called in an +ensure+ clause so
+      #   {MultipartUpload#close} is called in an `ensure` clause so
       #   that the upload will always be either completed or
       #   aborted.
       #
@@ -651,18 +657,18 @@ module AWS
       #
       # @option options [Hash] :metadata A hash of metadata to be
       #   included with the object.  These will be sent to S3 as
-      #   headers prefixed with +x-amz-meta+.  Each name, value pair
+      #   headers prefixed with `x-amz-meta`.  Each name, value pair
       #   must conform to US-ASCII.
       #
       # @option options [Symbol] :acl (private) A canned access
       #   control policy.  Valid values are:
       #
-      #   * +:private+
-      #   * +:public_read+
-      #   * +:public_read_write+
-      #   * +:authenticated_read+
-      #   * +:bucket_owner_read+
-      #   * +:bucket_owner_full_control+
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read`
+      #   * `:bucket_owner_full_control`
       #
       # @option options [Boolean] :reduced_redundancy (false) If true,
       #   Reduced Redundancy Storage will be enabled for the uploaded
@@ -679,7 +685,7 @@ module AWS
       # @option options :content_encoding [String] Specifies what
       #   content encodings have been applied to the object and thus
       #   what decoding mechanisms must be applied to obtain the
-      #   media-type referenced by the +Content-Type+ header field.
+      #   media-type referenced by the `Content-Type` header field.
       #   See
       #   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
       #
@@ -688,10 +694,10 @@ module AWS
       #
       # @option options [Symbol] :server_side_encryption (nil) If this
       #   option is set, the object will be stored using server side
-      #   encryption.  The only valid value is +:aes256+, which
+      #   encryption.  The only valid value is `:aes256`, which
       #   specifies that the object should be stored using the AES
       #   encryption algorithm with 256 bit keys.  By default, this
-      #   option uses the value of the +:s3_server_side_encryption+
+      #   option uses the value of the `:s3_server_side_encryption`
       #   option in the current configuration; for more information,
       #   see {AWS.config}.
       #
@@ -736,23 +742,23 @@ module AWS
       # deleting the old object.  This function returns the
       # new object once this is done.
       #
-      #   bucket = s3.buckets['old-bucket']
-      #   old_obj = bucket.objects['old-key']
+      #     bucket = s3.buckets['old-bucket']
+      #     old_obj = bucket.objects['old-key']
       #
-      #   # renaming an object returns a new object
-      #   new_obj = old_obj.move_to('new-key')
+      #     # renaming an object returns a new object
+      #     new_obj = old_obj.move_to('new-key')
       #
-      #   old_obj.key     #=> 'old-key'
-      #   old_obj.exists? #=> false
+      #     old_obj.key     #=> 'old-key'
+      #     old_obj.exists? #=> false
       #
-      #   new_obj.key     #=> 'new-key'
-      #   new_obj.exists? #=> true
+      #     new_obj.key     #=> 'new-key'
+      #     new_obj.exists? #=> true
       #
       # If you need to move an object to a different bucket, pass
-      # +:bucket+ or +:bucket_name+.
+      # `:bucket` or `:bucket_name`.
       #
-      #   obj = s3.buckets['old-bucket'].objects['old-key']
-      #   obj.move_to('new-key', :bucket_name => 'new_bucket')
+      #     obj = s3.buckets['old-bucket'].objects['old-key']
+      #     obj.move_to('new-key', :bucket_name => 'new_bucket')
       #
       # If the copy succeeds, but the then the delete fails, an error
       # will be raised.
@@ -812,19 +818,19 @@ module AWS
       # @option options [Symbol] :acl (private) A canned access
       #   control policy.  Valid values are:
       #
-      #   * +:private+
-      #   * +:public_read+
-      #   * +:public_read_write+
-      #   * +:authenticated_read+
-      #   * +:bucket_owner_read+
-      #   * +:bucket_owner_full_control+
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read`
+      #   * `:bucket_owner_full_control`
       #
       # @option options [Symbol] :server_side_encryption (nil) If this
       #   option is set, the object will be stored using server side
-      #   encryption.  The only valid value is +:aes256+, which
+      #   encryption.  The only valid value is `:aes256`, which
       #   specifies that the object should be stored using the AES
       #   encryption algorithm with 256 bit keys.  By default, this
-      #   option uses the value of the +:s3_server_side_encryption+
+      #   option uses the value of the `:s3_server_side_encryption`
       #   option in the current configuration; for more information,
       #   see {AWS.config}.
       #
@@ -924,23 +930,23 @@ module AWS
       # @option options [Symbol] :acl (private) A canned access
       #   control policy.  Valid values are:
       #
-      #   * +:private+
-      #   * +:public_read+
-      #   * +:public_read_write+
-      #   * +:authenticated_read+
-      #   * +:bucket_owner_read+
-      #   * +:bucket_owner_full_control+
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read`
+      #   * `:bucket_owner_full_control`
       #
       # @option options [Symbol] :server_side_encryption (nil) If this
       #   option is set, the object will be stored using server side
-      #   encryption.  The only valid value is +:aes256+, which
+      #   encryption.  The only valid value is `:aes256`, which
       #   specifies that the object should be stored using the AES
       #   encryption algorithm with 256 bit keys.  By default, this
-      #   option uses the value of the +:s3_server_side_encryption+
+      #   option uses the value of the `:s3_server_side_encryption`
       #   option in the current configuration; for more information,
       #   see {AWS.config}.
       #
-      # @option options [Boolean] :client_side_encrypted (false) When +true+,
+      # @option options [Boolean] :client_side_encrypted (false) When `true`,
       #   the client-side encryption materials will be copied. Without this
       #   option, the key and iv are not guaranteed to be transferred to
       #   the new object.
@@ -977,27 +983,27 @@ module AWS
       # method, the data will be yielded to the block in chunks as it
       # is read off the HTTP response.
       #
-      # === Read an object from S3 in chunks
+      # ### Read an object from S3 in chunks
       #
       # When downloading large objects it is recommended to pass a block
       # to #read.  Data will be yielded to the block as it is read off
       # the HTTP response.
       #
-      #   # read an object from S3 to a file
-      #   File.open('output.txt', 'w') do |file|
-      #     bucket.objects['key'].read do |chunk|
-      #       file.write(chunk)
+      #     # read an object from S3 to a file
+      #     File.open('output.txt', 'w') do |file|
+      #       bucket.objects['key'].read do |chunk|
+      #         file.write(chunk)
+      #       end
       #     end
-      #   end
       #
-      # === Reading an object without a block
+      # ### Reading an object without a block
       #
       # When you omit the block argument to #read, then the entire
       # HTTP response and read and the object data is loaded into
       # memory.
       #
-      #   bucket.objects['key'].read
-      #   #=> 'object-contents-here'
+      #     bucket.objects['key'].read
+      #     #=> 'object-contents-here'
       #
       # @param [Hash] options
       #
@@ -1006,19 +1012,19 @@ module AWS
       #
       # @option options [Time] :if_unmodified_since If specified, the
       #   method will raise
-      #   <tt>AWS::S3::Errors::PreconditionFailed</tt> unless the
+      #   `AWS::S3::Errors::PreconditionFailed` unless the
       #   object has not been modified since the given time.
       #
       # @option options [Time] :if_modified_since If specified, the
-      #   method will raise <tt>AWS::S3::Errors::NotModified</tt> if
+      #   method will raise `AWS::S3::Errors::NotModified` if
       #   the object has not been modified since the given time.
       #
       # @option options [String] :if_match If specified, the method
-      #   will raise <tt>AWS::S3::Errors::PreconditionFailed</tt>
+      #   will raise `AWS::S3::Errors::PreconditionFailed`
       #   unless the object ETag matches the provided value.
       #
       # @option options [String] :if_none_match If specified, the
-      #   method will raise <tt>AWS::S3::Errors::NotModified</tt> if
+      #   method will raise `AWS::S3::Errors::NotModified` if
       #   the object ETag matches the provided value.
       #
       # @option options [Range] :range A byte range to read data from
@@ -1026,9 +1032,9 @@ module AWS
       # @option options [OpenSSL::PKey::RSA, String] :encryption_key
       #   (nil) If this option is set, the object will be decrypted using
       #   envelope encryption. The valid values are OpenSSL asymmetric keys
-      #   +OpenSSL::Pkey::RSA+ or strings representing symmetric keys
-      #   of an AES-128/192/256-ECB cipher as a +String+.
-      #   This value defaults to the value in +s3_encryption_key+;
+      #   `OpenSSL::Pkey::RSA` or strings representing symmetric keys
+      #   of an AES-128/192/256-ECB cipher as a `String`.
+      #   This value defaults to the value in `s3_encryption_key`;
       #   for more information, see {AWS.config}.
       #
       #   Symmetric Keys:
@@ -1040,10 +1046,10 @@ module AWS
       #   key = OpenSSL::PKey::RSA.new(KEY_SIZE)
       #
       # @option options [Symbol] :encryption_materials_location (:metadata)
-      #   Set this to +:instruction_file+ if the encryption materials
+      #   Set this to `:instruction_file` if the encryption materials
       #   are not stored in the object metadata
       #
-      # @note +:range+ option cannot be used with client-side encryption
+      # @note `:range` option cannot be used with client-side encryption
       #
       # @note All decryption reads incur at least an extra HEAD operation.
       #
@@ -1074,16 +1080,16 @@ module AWS
       end
 
       # Returns the object's access control list.  This will be an
-      # instance of AccessControlList, plus an additional +change+
+      # instance of AccessControlList, plus an additional `change`
       # method:
       #
-      #  object.acl.change do |acl|
-      #    # remove any grants to someone other than the bucket owner
-      #    owner_id = object.bucket.owner.id
-      #    acl.grants.reject! do |g|
-      #      g.grantee.canonical_user_id != owner_id
-      #    end
-      #  end
+      #     object.acl.change do |acl|
+      #       # remove any grants to someone other than the bucket owner
+      #       owner_id = object.bucket.owner.id
+      #       acl.grants.reject! do |g|
+      #         g.grantee.canonical_user_id != owner_id
+      #       end
+      #     end
       #
       # Note that changing the ACL is not an atomic operation; it
       # fetches the current ACL, yields it to the block, and then
@@ -1130,26 +1136,30 @@ module AWS
       # the permissions of the object.
       #
       # @example Generate a url to read an object
+      #
       #   bucket.objects.myobject.url_for(:read)
       #
       # @example Generate a url to delete an object
+      #
       #   bucket.objects.myobject.url_for(:delete)
       #
       # @example Override response headers for reading an object
+      #
       #   object = bucket.objects.myobject
       #   url = object.url_for(:read,
       #                        :response_content_type => "application/json")
       #
       # @example Generate a url that expires in 10 minutes
+      #
       #   bucket.objects.myobject.url_for(:read, :expires => 10*60)
       #
       # @param [Symbol, String] method The HTTP verb or object
       #   method for which the returned URL will be valid.  Valid
       #   values:
       #
-      #   * +:get+ or +:read+
-      #   * +:put+ or +:write+
-      #   * +:delete+
+      #   * `:get` or `:read`
+      #   * `:put` or `:write`
+      #   * `:delete`
       #
       # @param [Hash] options Additional options for generating the URL.
       #
@@ -1164,7 +1174,7 @@ module AWS
       #   secure (HTTPS) URL or a plain HTTP url.
       #
       # @option options [String] :endpoint Sets the hostname of the
-      #   endpoint (overrides config.s3_endpoint).
+      #   endpoint.
       #
       # @option options [Integer] :port Sets the port of the
       #   endpoint (overrides config.s3_port).
@@ -1254,7 +1264,7 @@ module AWS
       #   lower cost.  Otherwise, the object will be copied and stored
       #   with the standard storage class.
       #
-      # @return [true,false] The +value+ parameter.
+      # @return [true,false] The `value` parameter.
       def reduced_redundancy= value
         copy_from(key, :reduced_redundancy => value)
         value
@@ -1287,7 +1297,7 @@ module AWS
         end
       end
 
-      # @return [Boolean] Returns +true+ if the :data option is large or
+      # @return [Boolean] Returns `true` if the :data option is large or
       #   guessed to be larger than a configured threshold.
       def use_multipart? options
         estimated_content_length(options) > multipart_threshold(options) and
@@ -1379,7 +1389,7 @@ module AWS
 
       def request_for_signing(options)
 
-        port = [443, 80].include?(config.s3_port) ? 
+        port = [443, 80].include?(config.s3_port) ?
           (options[:secure] ? 443 : 80) :
           config.s3_port
 
@@ -1674,13 +1684,13 @@ module AWS
         end
       end
 
-      # @return [String] Encodes a +String+ in base 64 regardless of version of
+      # @return [String] Encodes a `String` in base 64 regardless of version of
       #   Ruby for http headers (removes newlines).
       def encode64 input
         Base64.encode64(input).split("\n") * ""
       end
 
-      # @return [String] Decodes a +String+ in base 64.
+      # @return [String] Decodes a `String` in base 64.
       def decode64 input
         Base64.decode64(input)
       end